summaryrefslogtreecommitdiff
path: root/ext
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-12-08 00:26:56 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2012-12-08 00:26:56 +0000
commit3adc9834d18ee6ff67dfca060eee170025ce3fef (patch)
tree8da48bacbb32eebef295346e5235757e34555307 /ext
parent1c9e3155959ff0841c57b89a40fa47f2099c4732 (diff)
* ext/openssl/ossl_x509name.c: Completed documentation for
OpenSSL::X509::Name. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38268 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext')
-rw-r--r--ext/openssl/ossl_x509name.c104
1 files changed, 97 insertions, 7 deletions
diff --git a/ext/openssl/ossl_x509name.c b/ext/openssl/ossl_x509name.c
index a8f288f4a59..4b397055ab7 100644
--- a/ext/openssl/ossl_x509name.c
+++ b/ext/openssl/ossl_x509name.c
@@ -111,10 +111,23 @@ ossl_x509name_init_i(VALUE i, VALUE args)
/*
* call-seq:
- * X509::Name.new => name
- * X509::Name.new(string) => name
- * X509::Name.new(dn) => name
- * X509::Name.new(dn, template) => name
+ * X509::Name.new => name
+ * X509::Name.new(der) => name
+ * X509::Name.new(distinguished_name) => name
+ * X509::Name.new(distinguished_name, template) => name
+ *
+ * Creates a new Name.
+ *
+ * A name may be created from a DER encoded string +der+, an Array
+ * representing a +distinguished_name+ or a +distinguished_name+ along with a
+ * +template+.
+ *
+ * name = OpenSSL::X509::Name.new [['CN', 'nobody'], ['DC', 'example']]
+ *
+ * name = OpenSSL::X509::Name.new name.to_der
+ *
+ * See add_entry for a description of the +distinguished_name+ Array's
+ * contents
*/
static VALUE
ossl_x509name_initialize(int argc, VALUE *argv, VALUE self)
@@ -154,6 +167,16 @@ ossl_x509name_initialize(int argc, VALUE *argv, VALUE self)
/*
* call-seq:
* name.add_entry(oid, value [, type]) => self
+ *
+ * Adds a new entry with the given +oid+ and +value+ to this name. The +oid+
+ * is an object identifier defined in ASN.1. Some common OIDs are:
+ *
+ * C:: Country Name
+ * CN:: Common Name
+ * DC:: Domain Component
+ * O:: Organization Name
+ * OU:: Organizational Unit Name
+ * ST:: State or Province Name
*/
static
VALUE ossl_x509name_add_entry(int argc, VALUE *argv, VALUE self)
@@ -192,7 +215,14 @@ ossl_x509name_to_s_old(VALUE self)
/*
* call-seq:
* name.to_s => string
- * name.to_s(integer) => string
+ * name.to_s(flags) => string
+ *
+ * Returns this name as a Distinguished Name string. +flags+ may be one of:
+ *
+ * * OpenSSL::X509::Name::COMPAT
+ * * OpenSSL::X509::Name::RFC2253
+ * * OpenSSL::X509::Name::ONELINE
+ * * OpenSSL::X509::Name::MULTILINE
*/
static VALUE
ossl_x509name_to_s(int argc, VALUE *argv, VALUE self)
@@ -221,6 +251,9 @@ ossl_x509name_to_s(int argc, VALUE *argv, VALUE self)
/*
* call-seq:
* name.to_a => [[name, data, type], ...]
+ *
+ * Returns an Array representation of the distinguished name suitable for
+ * passing to ::new
*/
static VALUE
ossl_x509name_to_a(VALUE self)
@@ -293,6 +326,12 @@ ossl_x509name_cmp(VALUE self, VALUE other)
return INT2FIX(0);
}
+/*
+ * call-seq:
+ * name.eql? other => boolean
+ *
+ * Returns true if +name+ and +other+ refer to the same hash key.
+ */
static VALUE
ossl_x509name_eql(VALUE self, VALUE other)
{
@@ -329,7 +368,7 @@ ossl_x509name_hash(VALUE self)
* call-seq:
* name.hash_old => integer
*
- * hash_old returns MD5 based hash used in OpenSSL 0.9.X.
+ * Returns an MD5 based hash used in OpenSSL 0.9.X.
*/
static VALUE
ossl_x509name_hash_old(VALUE self)
@@ -348,6 +387,8 @@ ossl_x509name_hash_old(VALUE self)
/*
* call-seq:
* name.to_der => string
+ *
+ * Converts the name to DER encoding
*/
static VALUE
ossl_x509name_to_der(VALUE self)
@@ -370,8 +411,19 @@ ossl_x509name_to_der(VALUE self)
}
/*
- * INIT
+ * Document-class: OpenSSL::X509::Name
+ *
+ * An X.509 name represents a hostname, email address or other entity
+ * associated with a public key.
+ *
+ * You can create a Name by parsing a distinguished name String or by
+ * supplying the distinguished name as an Array.
+ *
+ * name = OpenSSL::X509::Name.parse 'CN=nobody/DC=example'
+ *
+ * name = OpenSSL::X509::Name.new [['CN', 'nobody'], ['DC', 'example']]
*/
+
void
Init_ossl_x509name()
{
@@ -400,6 +452,11 @@ Init_ossl_x509name()
utf8str = INT2NUM(V_ASN1_UTF8STRING);
ptrstr = INT2NUM(V_ASN1_PRINTABLESTRING);
ia5str = INT2NUM(V_ASN1_IA5STRING);
+
+ /* Document-const: DEFAULT_OBJECT_TYPE
+ *
+ * The default object type for name entries.
+ */
rb_define_const(cX509Name, "DEFAULT_OBJECT_TYPE", utf8str);
hash = rb_hash_new();
RHASH(hash)->ifnone = utf8str;
@@ -410,10 +467,43 @@ Init_ossl_x509name()
rb_hash_aset(hash, rb_str_new2("DC"), ia5str);
rb_hash_aset(hash, rb_str_new2("domainComponent"), ia5str);
rb_hash_aset(hash, rb_str_new2("emailAddress"), ia5str);
+
+ /* Document-const: OBJECT_TYPE_TEMPLATE
+ *
+ * The default object type template for name entries.
+ */
rb_define_const(cX509Name, "OBJECT_TYPE_TEMPLATE", hash);
+ /* Document-const: COMPAT
+ *
+ * A flag for #to_s.
+ *
+ * Breaks the name returned into multiple lines if longer than 80
+ * characters.
+ */
rb_define_const(cX509Name, "COMPAT", ULONG2NUM(XN_FLAG_COMPAT));
+
+ /* Document-const: RFC2253
+ *
+ * A flag for #to_s.
+ *
+ * Returns an RFC2253 format name.
+ */
rb_define_const(cX509Name, "RFC2253", ULONG2NUM(XN_FLAG_RFC2253));
+
+ /* Document-const: ONELINE
+ *
+ * A flag for #to_s.
+ *
+ * Returns a more readable format than RFC2253.
+ */
rb_define_const(cX509Name, "ONELINE", ULONG2NUM(XN_FLAG_ONELINE));
+
+ /* Document-const: MULTILINE
+ *
+ * A flag for #to_s.
+ *
+ * Returns a multiline format.
+ */
rb_define_const(cX509Name, "MULTILINE", ULONG2NUM(XN_FLAG_MULTILINE));
}