From c68e46f089626329031c2ca75e7868277d58cee6 Mon Sep 17 00:00:00 2001 From: Kazuki Yamaguchi Date: Thu, 23 Feb 2017 23:57:22 +0900 Subject: Fix RDoc markup Ruby core uses _str_ for emphasizing argument names and +str+ for codes. Match with the rule for better rendering. --- ext/openssl/ossl.c | 7 +- ext/openssl/ossl_asn1.c | 189 +++++++++++++++++++++-------------------- ext/openssl/ossl_bn.c | 39 ++++----- ext/openssl/ossl_cipher.c | 28 +++--- ext/openssl/ossl_digest.c | 6 +- ext/openssl/ossl_engine.c | 90 ++++++++++---------- ext/openssl/ossl_hmac.c | 20 ++--- ext/openssl/ossl_ns_spki.c | 12 +-- ext/openssl/ossl_ocsp.c | 79 +++++++++-------- ext/openssl/ossl_pkcs12.c | 26 +++--- ext/openssl/ossl_pkey.c | 22 ++--- ext/openssl/ossl_pkey_dh.c | 20 ++--- ext/openssl/ossl_pkey_dsa.c | 28 +++--- ext/openssl/ossl_pkey_ec.c | 34 ++++---- ext/openssl/ossl_pkey_rsa.c | 34 ++++---- ext/openssl/ossl_rand.c | 24 +++--- ext/openssl/ossl_ssl.c | 34 ++++---- ext/openssl/ossl_ssl_session.c | 2 +- ext/openssl/ossl_x509cert.c | 8 +- ext/openssl/ossl_x509ext.c | 12 +-- ext/openssl/ossl_x509name.c | 32 ++++--- ext/openssl/ossl_x509store.c | 25 +++--- 22 files changed, 390 insertions(+), 381 deletions(-) (limited to 'ext/openssl') diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c index bcadc3e1..0cc88c7b 100644 --- a/ext/openssl/ossl.c +++ b/ext/openssl/ossl.c @@ -328,7 +328,8 @@ ossl_clear_error(void) * * See any remaining errors held in queue. * - * Any errors you see here are probably due to a bug in ruby's OpenSSL implementation. + * Any errors you see here are probably due to a bug in Ruby's OpenSSL + * implementation. */ VALUE ossl_get_errors(void) @@ -452,7 +453,7 @@ mem_check_start(VALUE self) * Prints detected memory leaks to standard error. This cleans the global state * up thus you cannot use any methods of the library after calling this. * - * Returns true if leaks detected, false otherwise. + * Returns +true+ if leaks detected, +false+ otherwise. * * This is available only when built with a capable OpenSSL and --enable-debug * configure option. @@ -568,7 +569,7 @@ static void Init_ossl_locks(void) /* * OpenSSL provides SSL, TLS and general purpose cryptography. It wraps the - * OpenSSL[http://www.openssl.org/] library. + * OpenSSL[https://www.openssl.org/] library. * * = Examples * diff --git a/ext/openssl/ossl_asn1.c b/ext/openssl/ossl_asn1.c index 9b554820..d2914821 100644 --- a/ext/openssl/ossl_asn1.c +++ b/ext/openssl/ossl_asn1.c @@ -645,12 +645,12 @@ ossl_asn1_class2sym(int tc) * call-seq: * OpenSSL::ASN1::ASN1Data.new(value, tag, tag_class) => ASN1Data * - * +value+: Please have a look at Constructive and Primitive to see how Ruby + * _value_: Please have a look at Constructive and Primitive to see how Ruby * types are mapped to ASN.1 types and vice versa. * - * +tag+: A +Number+ indicating the tag number. + * _tag_: An Integer indicating the tag number. * - * +tag_class+: A +Symbol+ indicating the tag class. Please cf. ASN1 for + * _tag_class_: A Symbol indicating the tag class. Please cf. ASN1 for * possible values. * * == Example @@ -950,13 +950,13 @@ int_ossl_decode_sanity_check(long len, long read, long offset) * * If a block is given, it prints out each of the elements encountered. * Block parameters are (in that order): - * * depth: The recursion depth, plus one with each constructed value being encountered (Number) - * * offset: Current byte offset (Number) - * * header length: Combined length in bytes of the Tag and Length headers. (Number) - * * length: The overall remaining length of the entire data (Number) + * * depth: The recursion depth, plus one with each constructed value being encountered (Integer) + * * offset: Current byte offset (Integer) + * * header length: Combined length in bytes of the Tag and Length headers. (Integer) + * * length: The overall remaining length of the entire data (Integer) * * constructed: Whether this value is constructed or not (Boolean) * * tag_class: Current tag class (Symbol) - * * tag: The current tag (Number) + * * tag: The current tag number (Integer) * * == Example * der = File.binread('asn1data.der') @@ -986,9 +986,9 @@ ossl_asn1_traverse(VALUE self, VALUE obj) * call-seq: * OpenSSL::ASN1.decode(der) -> ASN1Data * - * Decodes a BER- or DER-encoded value and creates an ASN1Data instance. +der+ - * may be a +String+ or any object that features a +#to_der+ method transforming - * it into a BER-/DER-encoded +String+. + * Decodes a BER- or DER-encoded value and creates an ASN1Data instance. _der_ + * may be a String or any object that features a +.to_der+ method transforming + * it into a BER-/DER-encoded String+ * * == Example * der = File.binread('asn1data') @@ -1016,9 +1016,9 @@ ossl_asn1_decode(VALUE self, VALUE obj) * call-seq: * OpenSSL::ASN1.decode_all(der) -> Array of ASN1Data * - * Similar to +decode+ with the difference that +decode+ expects one - * distinct value represented in +der+. +decode_all+ on the contrary - * decodes a sequence of sequential BER/DER values lined up in +der+ + * Similar to #decode with the difference that #decode expects one + * distinct value represented in _der_. #decode_all on the contrary + * decodes a sequence of sequential BER/DER values lined up in _der_ * and returns them as an array. * * == Example @@ -1053,19 +1053,19 @@ ossl_asn1_decode_all(VALUE self, VALUE obj) /* * call-seq: - * OpenSSL::ASN1::Primitive.new( value [, tag, tagging, tag_class ]) => Primitive + * OpenSSL::ASN1::Primitive.new(value [, tag, tagging, tag_class ]) => Primitive * - * +value+: is mandatory. + * _value_: is mandatory. * - * +tag+: optional, may be specified for tagged values. If no +tag+ is + * _tag_: optional, may be specified for tagged values. If no _tag_ is * specified, the UNIVERSAL tag corresponding to the Primitive sub-class * is used by default. * - * +tagging+: may be used as an encoding hint to encode a value either + * _tagging_: may be used as an encoding hint to encode a value either * explicitly or implicitly, see ASN1 for possible values. * - * +tag_class+: if +tag+ and +tagging+ are +nil+ then this is set to - * +:UNIVERSAL+ by default. If either +tag+ or +tagging+ are set then + * _tag_class_: if _tag_ and _tagging_ are +nil+ then this is set to + * +:UNIVERSAL+ by default. If either _tag_ or _tagging_ are set then * +:CONTEXT_SPECIFIC+ is used as the default. For possible values please * cf. ASN1. * @@ -1129,7 +1129,7 @@ ossl_asn1eoc_initialize(VALUE self) { * call-seq: * asn1.to_der => DER-encoded String * - * See ASN1Data#to_der for details. * + * See ASN1Data#to_der for details. */ static VALUE ossl_asn1prim_to_der(VALUE self) @@ -1261,8 +1261,8 @@ ossl_asn1cons_to_der(VALUE self) * call-seq: * asn1_ary.each { |asn1| block } => asn1_ary * - * Calls block once for each element in +self+, passing that element - * as parameter +asn1+. If no block is given, an enumerator is returned + * Calls the given block once for each element in self, passing that element + * as parameter _asn1_. If no block is given, an enumerator is returned * instead. * * == Example @@ -1282,8 +1282,8 @@ ossl_asn1cons_each(VALUE self) * call-seq: * OpenSSL::ASN1::ObjectId.register(object_id, short_name, long_name) * - * This adds a new ObjectId to the internal tables. Where +object_id+ is the - * numerical form, +short_name+ is the short name, and +long_name+ is the long + * This adds a new ObjectId to the internal tables. Where _object_id_ is the + * numerical form, _short_name_ is the short name, and _long_name_ is the long * name. * * Returns +true+ if successful. Raises an OpenSSL::ASN1::ASN1Error if it fails. @@ -1302,14 +1302,13 @@ ossl_asn1obj_s_register(VALUE self, VALUE oid, VALUE sn, VALUE ln) return Qtrue; } -/* Document-method: OpenSSL::ASN1::ObjectId#sn +/* + * call-seq: + * oid.sn -> string + * oid.short_name -> string * * The short name of the ObjectId, as defined in . */ -/* Document-method: OpenSSL::ASN1::ObjectId#short_name - * - * +short_name+ is an alias to +sn+ - */ static VALUE ossl_asn1obj_get_sn(VALUE self) { @@ -1323,14 +1322,13 @@ ossl_asn1obj_get_sn(VALUE self) return ret; } -/* Document-method: OpenSSL::ASN1::ObjectId#ln +/* + * call-seq: + * oid.ln -> string + * oid.long_name -> string * * The long name of the ObjectId, as defined in . */ -/* Document-method: OpenSSL::ASN1::ObjectId#long_name - * - * +long_name+ is an alias to +ln+ - */ static VALUE ossl_asn1obj_get_ln(VALUE self) { @@ -1344,9 +1342,12 @@ ossl_asn1obj_get_ln(VALUE self) return ret; } -/* Document-method: OpenSSL::ASN1::ObjectId#oid +/* + * call-seq: + * oid.oid -> string * - * The object identifier as a +String+, e.g. "1.2.3.4.5" + * Returns a String representing the Object Identifier in the dot notation, + * e.g. "1.2.3.4.5" */ static VALUE ossl_asn1obj_get_oid(VALUE self) @@ -1439,13 +1440,13 @@ Init_ossl_asn1(void) * == ASN.1 class hierarchy * * The base class representing ASN.1 structures is ASN1Data. ASN1Data offers - * attributes to read and set the +tag+, the +tag_class+ and finally the - * +value+ of a particular ASN.1 item. Upon parsing, any tagged values + * attributes to read and set the _tag_, the _tag_class_ and finally the + * _value_ of a particular ASN.1 item. Upon parsing, any tagged values * (implicit or explicit) will be represented by ASN1Data instances because * their "real type" can only be determined using out-of-band information * from the ASN.1 type declaration. Since this information is normally * known when encoding a type, all sub-classes of ASN1Data offer an - * additional attribute +tagging+ that allows to encode a value implicitly + * additional attribute _tagging_ that allows to encode a value implicitly * (+:IMPLICIT+) or explicitly (+:EXPLICIT+). * * === Constructive @@ -1473,18 +1474,18 @@ Init_ossl_asn1(void) * Please cf. Primitive documentation for details on sub-classes and * their respective mappings of ASN.1 data types to Ruby objects. * - * == Possible values for +tagging+ + * == Possible values for _tagging_ * * When constructing an ASN1Data object the ASN.1 type definition may * require certain elements to be either implicitly or explicitly tagged. - * This can be achieved by setting the +tagging+ attribute manually for + * This can be achieved by setting the _tagging_ attribute manually for * sub-classes of ASN1Data. Use the symbol +:IMPLICIT+ for implicit * tagging and +:EXPLICIT+ if the element requires explicit tagging. * - * == Possible values for +tag_class+ + * == Possible values for _tag_class_ * * It is possible to create arbitrary ASN1Data objects that also support - * a PRIVATE or APPLICATION tag class. Possible values for the +tag_class+ + * a PRIVATE or APPLICATION tag class. Possible values for the _tag_class_ * attribute are: * * +:UNIVERSAL+ (the default for untagged values) * * +:CONTEXT_SPECIFIC+ (the default for tagged values) @@ -1586,9 +1587,9 @@ Init_ossl_asn1(void) * * An implicitly 1-tagged INTEGER value will be parsed as an * ASN1Data with - * * +tag+ equal to 1 - * * +tag_class+ equal to +:CONTEXT_SPECIFIC+ - * * +value+ equal to a +String+ that carries the raw encoding + * * _tag_ equal to 1 + * * _tag_class_ equal to +:CONTEXT_SPECIFIC+ + * * _value_ equal to a String that carries the raw encoding * of the INTEGER. * This implies that a subsequent decoding step is required to * completely decode implicitly tagged values. @@ -1597,9 +1598,9 @@ Init_ossl_asn1(void) * * An explicitly 1-tagged INTEGER value will be parsed as an * ASN1Data with - * * +tag+ equal to 1 - * * +tag_class+ equal to +:CONTEXT_SPECIFIC+ - * * +value+ equal to an +Array+ with one single element, an + * * _tag_ equal to 1 + * * _tag_class_ equal to +:CONTEXT_SPECIFIC+ + * * _value_ equal to an Array with one single element, an * instance of OpenSSL::ASN1::Integer, i.e. the inner element * is the non-tagged primitive value, and the tagging is represented * in the outer ASN1Data @@ -1660,16 +1661,16 @@ Init_ossl_asn1(void) */ rb_attr(cASN1Data, rb_intern("value"), 1, 1, 0); /* - * A +Number+ representing the tag number of this ASN1Data. Never +nil+. + * An Integer representing the tag number of this ASN1Data. Never +nil+. */ rb_attr(cASN1Data, rb_intern("tag"), 1, 1, 0); /* - * A +Symbol+ representing the tag class of this ASN1Data. Never +nil+. + * A Symbol representing the tag class of this ASN1Data. Never +nil+. * See ASN1Data for possible values. */ rb_attr(cASN1Data, rb_intern("tag_class"), 1, 1, 0); /* - * Never +nil+. A +Boolean+ indicating whether the encoding was infinite + * Never +nil+. A boolean value indicating whether the encoding was infinite * length (in the case of parsing) or whether an infinite length encoding * shall be used (in the encoding case). * In DER, every value has a finite length associated with it. But in @@ -1692,41 +1693,41 @@ Init_ossl_asn1(void) /* Document-class: OpenSSL::ASN1::Primitive * * The parent class for all primitive encodings. Attributes are the same as - * for ASN1Data, with the addition of +tagging+. + * for ASN1Data, with the addition of _tagging_ * Primitive values can never be infinite length encodings, thus it is not - * possible to set the +infinite_length+ attribute for Primitive and its + * possible to set the _infinite_length_ attribute for Primitive and its * sub-classes. * * == Primitive sub-classes and their mapping to Ruby classes - * * OpenSSL::ASN1::EndOfContent <=> +value+ is always +nil+ - * * OpenSSL::ASN1::Boolean <=> +value+ is a +Boolean+ - * * OpenSSL::ASN1::Integer <=> +value+ is a +Number+ - * * OpenSSL::ASN1::BitString <=> +value+ is a +String+ - * * OpenSSL::ASN1::OctetString <=> +value+ is a +String+ - * * OpenSSL::ASN1::Null <=> +value+ is always +nil+ - * * OpenSSL::ASN1::Object <=> +value+ is a +String+ - * * OpenSSL::ASN1::Enumerated <=> +value+ is a +Number+ - * * OpenSSL::ASN1::UTF8String <=> +value+ is a +String+ - * * OpenSSL::ASN1::NumericString <=> +value+ is a +String+ - * * OpenSSL::ASN1::PrintableString <=> +value+ is a +String+ - * * OpenSSL::ASN1::T61String <=> +value+ is a +String+ - * * OpenSSL::ASN1::VideotexString <=> +value+ is a +String+ - * * OpenSSL::ASN1::IA5String <=> +value+ is a +String+ - * * OpenSSL::ASN1::UTCTime <=> +value+ is a +Time+ - * * OpenSSL::ASN1::GeneralizedTime <=> +value+ is a +Time+ - * * OpenSSL::ASN1::GraphicString <=> +value+ is a +String+ - * * OpenSSL::ASN1::ISO64String <=> +value+ is a +String+ - * * OpenSSL::ASN1::GeneralString <=> +value+ is a +String+ - * * OpenSSL::ASN1::UniversalString <=> +value+ is a +String+ - * * OpenSSL::ASN1::BMPString <=> +value+ is a +String+ + * * OpenSSL::ASN1::EndOfContent <=> _value_ is always +nil+ + * * OpenSSL::ASN1::Boolean <=> _value_ is +true+ or +false+ + * * OpenSSL::ASN1::Integer <=> _value_ is an Integer + * * OpenSSL::ASN1::BitString <=> _value_ is a String + * * OpenSSL::ASN1::OctetString <=> _value_ is a String + * * OpenSSL::ASN1::Null <=> _value_ is always +nil+ + * * OpenSSL::ASN1::Object <=> _value_ is a String + * * OpenSSL::ASN1::Enumerated <=> _value_ is an Integer + * * OpenSSL::ASN1::UTF8String <=> _value_ is a String + * * OpenSSL::ASN1::NumericString <=> _value_ is a String + * * OpenSSL::ASN1::PrintableString <=> _value_ is a String + * * OpenSSL::ASN1::T61String <=> _value_ is a String + * * OpenSSL::ASN1::VideotexString <=> _value_ is a String + * * OpenSSL::ASN1::IA5String <=> _value_ is a String + * * OpenSSL::ASN1::UTCTime <=> _value_ is a Time + * * OpenSSL::ASN1::GeneralizedTime <=> _value_ is a Time + * * OpenSSL::ASN1::GraphicString <=> _value_ is a String + * * OpenSSL::ASN1::ISO64String <=> _value_ is a String + * * OpenSSL::ASN1::GeneralString <=> _value_ is a String + * * OpenSSL::ASN1::UniversalString <=> _value_ is a String + * * OpenSSL::ASN1::BMPString <=> _value_ is a String * * == OpenSSL::ASN1::BitString * * === Additional attributes - * +unused_bits+: if the underlying BIT STRING's - * length is a multiple of 8 then +unused_bits+ is 0. Otherwise - * +unused_bits+ indicates the number of bits that are to be ignored in - * the final octet of the +BitString+'s +value+. + * _unused_bits_: if the underlying BIT STRING's + * length is a multiple of 8 then _unused_bits_ is 0. Otherwise + * _unused_bits_ indicates the number of bits that are to be ignored in + * the final octet of the BitString's _value_. * * == OpenSSL::ASN1::ObjectId * @@ -1735,15 +1736,15 @@ Init_ossl_asn1(void) * parsed ASN1 encodings. * * === Additional attributes - * * +sn+: the short name as defined in . - * * +ln+: the long name as defined in . - * * +oid+: the object identifier as a +String+, e.g. "1.2.3.4.5" - * * +short_name+: alias for +sn+. - * * +long_name+: alias for +ln+. + * * _sn_: the short name as defined in . + * * _ln_: the long name as defined in . + * * _oid_: the object identifier as a String, e.g. "1.2.3.4.5" + * * _short_name_: alias for _sn_. + * * _long_name_: alias for _ln_. * * == Examples * With the Exception of OpenSSL::ASN1::EndOfContent, each Primitive class - * constructor takes at least one parameter, the +value+. + * constructor takes at least one parameter, the _value_. * * === Creating EndOfContent * eoc = OpenSSL::ASN1::EndOfContent.new @@ -1757,7 +1758,7 @@ Init_ossl_asn1(void) /* * May be used as a hint for encoding a value either implicitly or * explicitly by setting it either to +:IMPLICIT+ or to +:EXPLICIT+. - * +tagging+ is not set when a ASN.1 structure is parsed using + * _tagging_ is not set when a ASN.1 structure is parsed using * OpenSSL::ASN1.decode. */ rb_attr(cASN1Primitive, rb_intern("tagging"), 1, 1, Qtrue); @@ -1767,9 +1768,9 @@ Init_ossl_asn1(void) /* Document-class: OpenSSL::ASN1::Constructive * - * The parent class for all constructed encodings. The +value+ attribute - * of a Constructive is always an +Array+. Attributes are the same as - * for ASN1Data, with the addition of +tagging+. + * The parent class for all constructed encodings. The _value_ attribute + * of a Constructive is always an Array. Attributes are the same as + * for ASN1Data, with the addition of _tagging_. * * == SET and SEQUENCE * @@ -1796,19 +1797,19 @@ Init_ossl_asn1(void) * * The only case where Constructive is used directly is for infinite * length encodings of primitive values. These encodings are always - * constructed, with the contents of the +value+ +Array+ being either + * constructed, with the contents of the _value_ Array being either * UNIVERSAL non-infinite length partial encodings of the actual value * or again constructive encodings with infinite length (i.e. infinite * length primitive encodings may be constructed recursively with another * infinite length value within an already infinite length value). Each * partial encoding must be of the same UNIVERSAL type as the overall * encoding. The value of the overall encoding consists of the - * concatenation of each partial encoding taken in sequence. The +value+ + * concatenation of each partial encoding taken in sequence. The _value_ * array of the outer infinite length value must end with a * OpenSSL::ASN1::EndOfContent instance. * * Please note that it is not possible to encode Constructive without - * the +infinite_length+ attribute being set to +true+, use + * the _infinite_length_ attribute being set to +true+, use * OpenSSL::ASN1::Sequence or OpenSSL::ASN1::Set in these cases instead. * * === Example - Infinite length OCTET STRING @@ -1832,7 +1833,7 @@ Init_ossl_asn1(void) /* * May be used as a hint for encoding a value either implicitly or * explicitly by setting it either to +:IMPLICIT+ or to +:EXPLICIT+. - * +tagging+ is not set when a ASN.1 structure is parsed using + * _tagging_ is not set when a ASN.1 structure is parsed using * OpenSSL::ASN1.decode. */ rb_attr(cASN1Constructive, rb_intern("tagging"), 1, 1, Qtrue); diff --git a/ext/openssl/ossl_bn.c b/ext/openssl/ossl_bn.c index dfe1b268..b0e8356a 100644 --- a/ext/openssl/ossl_bn.c +++ b/ext/openssl/ossl_bn.c @@ -176,8 +176,7 @@ ossl_bn_alloc(VALUE klass) return obj; } -/* Document-method: OpenSSL::BN.new - * +/* * call-seq: * OpenSSL::BN.new => aBN * OpenSSL::BN.new(bn) => aBN @@ -185,7 +184,7 @@ ossl_bn_alloc(VALUE klass) * OpenSSL::BN.new(string) => aBN * OpenSSL::BN.new(string, 0 | 2 | 10 | 16) => aBN * - * Construct a new OpenSSL BigNum object. + * Construct a new OpenSSL BIGNUM object. */ static VALUE ossl_bn_initialize(int argc, VALUE *argv, VALUE self) @@ -250,7 +249,7 @@ ossl_bn_initialize(int argc, VALUE *argv, VALUE self) * bn.to_s(base) => string * * === Parameters - * * +base+ - integer + * * _base_ - Integer * Valid values: * * 0 - MPI * * 2 - binary @@ -513,7 +512,6 @@ BIGNUM_2c(mod_sqr) BIGNUM_2c(mod_inverse) /* - * Document-method: OpenSSL::BN#/ * call-seq: * bn1 / bn2 => [result, remainder] * @@ -629,12 +627,11 @@ BIGNUM_BIT(clear_bit) */ BIGNUM_BIT(mask_bits) -/* Document-method: OpenSSL::BN#bit_set? +/* * call-seq: * bn.bit_set?(bit) => true | false * - * Returns boolean of whether +bit+ is set. - * Bitwise operations for openssl BIGNUMs. + * Tests bit _bit_ in _bn_ and returns +true+ if set, +false+ if not set. */ static VALUE ossl_bn_is_bit_set(VALUE self, VALUE bit) @@ -789,15 +786,15 @@ BIGNUM_RAND_RANGE(pseudo_rand) * call-seq: * BN.generate_prime(bits, [, safe [, add [, rem]]]) => bn * - * Generates a random prime number of bit length +bits+. If +safe+ is true, - * generates a safe prime. If +add+ is specified, generates a prime that + * Generates a random prime number of bit length _bits_. If _safe_ is set to + * +true+, generates a safe prime. If _add_ is specified, generates a prime that * fulfills condition p % add = rem. * * === Parameters - * * +bits+ - integer - * * +safe+ - boolean - * * +add+ - BN - * * +rem+ - BN + * * _bits_ - integer + * * _safe_ - boolean + * * _add_ - BN + * * _rem_ - BN */ static VALUE ossl_bn_s_generate_prime(int argc, VALUE *argv, VALUE klass) @@ -934,7 +931,7 @@ BIGNUM_CMP(ucmp) * call-seq: * bn == obj => true or false * - * Returns +true+ only if +obj+ has the same value as +bn+. Contrast this + * Returns +true+ only if _obj_ has the same value as _bn_. Contrast this * with OpenSSL::BN#eql?, which requires obj to be OpenSSL::BN. */ static VALUE @@ -959,7 +956,7 @@ ossl_bn_eq(VALUE self, VALUE other) * bn.eql?(obj) => true or false * * Returns true only if obj is a - * OpenSSL::BN with the same value as big. Contrast this + * OpenSSL::BN with the same value as bn. Contrast this * with OpenSSL::BN#==, which performs type conversions. */ static VALUE @@ -1010,12 +1007,12 @@ ossl_bn_hash(VALUE self) * bn.prime? => true | false * bn.prime?(checks) => true | false * - * Performs a Miller-Rabin probabilistic primality test with +checks+ - * iterations. If +nchecks+ is not specified, a number of iterations is used + * Performs a Miller-Rabin probabilistic primality test with _checks_ + * iterations. If _checks_ is not specified, a number of iterations is used * that yields a false positive rate of at most 2^-80 for random input. * * === Parameters - * * +checks+ - integer + * * _checks_ - integer */ static VALUE ossl_bn_is_prime(int argc, VALUE *argv, VALUE self) @@ -1050,8 +1047,8 @@ ossl_bn_is_prime(int argc, VALUE *argv, VALUE self) * first attempts trial divisions with some small primes. * * === Parameters - * * +checks+ - integer - * * +trial_div+ - boolean + * * _checks_ - integer + * * _trial_div_ - boolean */ static VALUE ossl_bn_is_prime_fasttest(int argc, VALUE *argv, VALUE self) diff --git a/ext/openssl/ossl_cipher.c b/ext/openssl/ossl_cipher.c index aed7fbb4..4ee76a97 100644 --- a/ext/openssl/ossl_cipher.c +++ b/ext/openssl/ossl_cipher.c @@ -108,7 +108,7 @@ ossl_cipher_alloc(VALUE klass) * call-seq: * Cipher.new(string) -> cipher * - * The string must contain a valid cipher name like "AES-128-CBC" or "3DES". + * The string must be a valid cipher name like "AES-128-CBC" or "3DES". * * A list of cipher names is available by calling OpenSSL::Cipher.ciphers. */ @@ -296,9 +296,9 @@ ossl_cipher_decrypt(int argc, VALUE *argv, VALUE self) * OpenSSL::PKCS5 instead. * * === Parameters - * * +salt+ must be an 8 byte string if provided. - * * +iterations+ is an integer with a default of 2048. - * * +digest+ is a Digest object that defaults to 'MD5' + * * _salt_ must be an 8 byte string if provided. + * * _iterations_ is an integer with a default of 2048. + * * _digest_ is a Digest object that defaults to 'MD5' * * A minimum of 1000 iterations is recommended. * @@ -365,12 +365,12 @@ ossl_cipher_update_long(EVP_CIPHER_CTX *ctx, unsigned char *out, long *out_len_p * cipher.update(data [, buffer]) -> string or buffer * * Encrypts data in a streaming fashion. Hand consecutive blocks of data - * to the +update+ method in order to encrypt it. Returns the encrypted + * to the #update method in order to encrypt it. Returns the encrypted * data chunk. When done, the output of Cipher#final should be additionally * added to the result. * - * If +buffer+ is given, the encryption/decryption result will be written to - * it. +buffer+ will be resized automatically. + * If _buffer_ is given, the encryption/decryption result will be written to + * it. _buffer_ will be resized automatically. */ static VALUE ossl_cipher_update(int argc, VALUE *argv, VALUE self) @@ -587,8 +587,8 @@ ossl_cipher_set_auth_data(VALUE self, VALUE data) * Gets the authentication tag generated by Authenticated Encryption Cipher * modes (GCM for example). This tag may be stored along with the ciphertext, * then set on the decryption cipher to authenticate the contents of the - * ciphertext against changes. If the optional integer parameter +tag_len+ is - * given, the returned tag will be +tag_len+ bytes long. If the parameter is + * ciphertext against changes. If the optional integer parameter _tag_len_ is + * given, the returned tag will be _tag_len_ bytes long. If the parameter is * omitted, the default length of 16 bytes or the length previously set by * #auth_tag_len= will be used. For maximum security, the longest possible * should be chosen. @@ -1004,9 +1004,9 @@ Init_ossl_cipher(void) * encryption and later decryption, the OpenSSL library still requires a * value to be set - "" may be used in case none is available. * - * An example using the GCM (Galois/Counter Mode). You have 16 bytes +key+, - * 12 bytes (96 bits) +nonce+ and the associated data +auth_data+. Be sure - * not to reuse the +key+ and +nonce+ pair. Reusing an nonce ruins the + * An example using the GCM (Galois/Counter Mode). You have 16 bytes _key_, + * 12 bytes (96 bits) _nonce_ and the associated data _auth_data_. Be sure + * not to reuse the _key_ and _nonce_ pair. Reusing an nonce ruins the * security gurantees of GCM mode. * * cipher = OpenSSL::Cipher::AES.new(128, :GCM).encrypt @@ -1017,8 +1017,8 @@ Init_ossl_cipher(void) * encrypted = cipher.update(data) + cipher.final * tag = cipher.auth_tag # produces 16 bytes tag by default * - * Now you are the receiver. You know the +key+ and have received +nonce+, - * +auth_data+, +encrypted+ and +tag+ through an untrusted network. Note + * Now you are the receiver. You know the _key_ and have received _nonce_, + * _auth_data_, _encrypted_ and _tag_ through an untrusted network. Note * that GCM accepts an arbitrary length tag between 1 and 16 bytes. You may * additionally need to check that the received tag has the correct length, * or you allow attackers to forge a valid single byte tag for the tampered diff --git a/ext/openssl/ossl_digest.c b/ext/openssl/ossl_digest.c index fdafda00..b93fe91c 100644 --- a/ext/openssl/ossl_digest.c +++ b/ext/openssl/ossl_digest.c @@ -106,15 +106,15 @@ VALUE ossl_digest_update(VALUE, VALUE); * call-seq: * Digest.new(string [, data]) -> Digest * - * Creates a Digest instance based on +string+, which is either the ln + * Creates a Digest instance based on _string_, which is either the ln * (long name) or sn (short name) of a supported digest algorithm. * - * If +data+ (a +String+) is given, it is used as the initial input to the + * If _data_ (a String) is given, it is used as the initial input to the * Digest instance, i.e. * * digest = OpenSSL::Digest.new('sha256', 'digestdata') * - * is equal to + * is equivalent to * * digest = OpenSSL::Digest.new('sha256') * digest.update('digestdata') diff --git a/ext/openssl/ossl_engine.c b/ext/openssl/ossl_engine.c index e840bfd9..887a04dd 100644 --- a/ext/openssl/ossl_engine.c +++ b/ext/openssl/ossl_engine.c @@ -72,14 +72,13 @@ static const rb_data_type_t ossl_engine_type = { 0, 0, RUBY_TYPED_FREE_IMMEDIATELY, }; -/* Document-method: OpenSSL::Engine.load - * +/* * call-seq: - * load(enginename = nil) + * OpenSSL::Engine.load(name = nil) * - * This method loads engines. If +name+ is nil, then all builtin engines are - * loaded. Otherwise, the given +name+, as a string, is loaded if available to - * your runtime, and returns true. If +name+ is not found, then nil is + * This method loads engines. If _name_ is nil, then all builtin engines are + * loaded. Otherwise, the given _name_, as a String, is loaded if available to + * your runtime, and returns true. If _name_ is not found, then nil is * returned. * */ @@ -153,9 +152,9 @@ ossl_engine_s_load(int argc, VALUE *argv, VALUE klass) #endif /* HAVE_ENGINE_LOAD_BUILTIN_ENGINES */ } -/* Document-method: OpenSSL::Engine.cleanup +/* * call-seq: - * OpenSSL::Engine.cleanup + * OpenSSL::Engine.cleanup * * It is only necessary to run cleanup when engines are loaded via * OpenSSL::Engine.load. However, running cleanup before exit is recommended. @@ -169,7 +168,9 @@ ossl_engine_s_cleanup(VALUE self) return Qnil; } -/* Document-method: OpenSSL::Engine.engines +/* + * call-seq: + * OpenSSL::Engine.engines -> [engine, ...] * * Returns an array of currently loaded engines. */ @@ -193,17 +194,16 @@ ossl_engine_s_engines(VALUE klass) return ary; } -/* Document-method: OpenSSL::Engine.by_id - * +/* * call-seq: - * by_id(name) -> engine + * OpenSSL::Engine.by_id(name) -> engine * - * Fetch the engine as specified by the +id+ String + * Fetches the engine as specified by the _id_ String. * * OpenSSL::Engine.by_id("openssl") * => # * - * See OpenSSL::Engine.engines for the currently loaded engines + * See OpenSSL::Engine.engines for the currently loaded engines. */ static VALUE ossl_engine_s_by_id(VALUE klass, VALUE id) @@ -227,9 +227,11 @@ ossl_engine_s_by_id(VALUE klass, VALUE id) return obj; } -/* Document-method: OpenSSL::Engine#id +/* + * call-seq: + * engine.id -> string * - * Get the id for this engine + * Gets the id for this engine. * * OpenSSL::Engine.load * OpenSSL::Engine.engines #=> [#, ...] @@ -244,9 +246,11 @@ ossl_engine_get_id(VALUE self) return rb_str_new2(ENGINE_get_id(e)); } -/* Document-method: OpenSSL::Engine#name +/* + * call-seq: + * engine.name -> string * - * Get the descriptive name for this engine + * Get the descriptive name for this engine. * * OpenSSL::Engine.load * OpenSSL::Engine.engines #=> [#, ...] @@ -262,7 +266,9 @@ ossl_engine_get_name(VALUE self) return rb_str_new2(ENGINE_get_name(e)); } -/* Document-method: OpenSSL::Engine#finish +/* + * call-seq: + * engine.finish -> nil * * Releases all internal structural references for this engine. * @@ -279,13 +285,12 @@ ossl_engine_finish(VALUE self) return Qnil; } -/* Document-method: OpenSSL::Engine#cipher - * +/* * call-seq: * engine.cipher(name) -> OpenSSL::Cipher * - * This returns an OpenSSL::Cipher by +name+, if it is available in this - * engine. + * Returns a new instance of OpenSSL::Cipher by _name_, if it is available in + * this engine. * * An EngineError will be raised if the cipher is unavailable. * @@ -312,12 +317,11 @@ ossl_engine_get_cipher(VALUE self, VALUE name) return ossl_cipher_new(ciph); } -/* Document-method: OpenSSL::Engine#digest - * +/* * call-seq: * engine.digest(name) -> OpenSSL::Digest * - * This returns an OpenSSL::Digest by +name+. + * Returns a new instance of OpenSSL::Digest by _name_. * * Will raise an EngineError if the digest is unavailable. * @@ -345,12 +349,11 @@ ossl_engine_get_digest(VALUE self, VALUE name) return ossl_digest_new(md); } -/* Document-method: OpenSSL::Engine#load_private_key - * +/* * call-seq: * engine.load_private_key(id = nil, data = nil) -> OpenSSL::PKey * - * Loads the given private key by +id+ and +data+. + * Loads the given private key identified by _id_ and _data_. * * An EngineError is raised of the OpenSSL::PKey is unavailable. * @@ -375,12 +378,11 @@ ossl_engine_load_privkey(int argc, VALUE *argv, VALUE self) return obj; } -/* Document-method: OpenSSL::Engine#load_public_key - * +/* * call-seq: * engine.load_public_key(id = nil, data = nil) -> OpenSSL::PKey * - * Loads the given private key by +id+ and +data+. + * Loads the given public key identified by _id_ and _data_. * * An EngineError is raised of the OpenSSL::PKey is unavailable. * @@ -403,16 +405,15 @@ ossl_engine_load_pubkey(int argc, VALUE *argv, VALUE self) return ossl_pkey_new(pkey); } -/* Document-method: OpenSSL::Engine#set_default - * +/* * call-seq: * engine.set_default(flag) * - * Set the defaults for this engine with the given +flag+. + * Set the defaults for this engine with the given _flag_. * * These flags are used to control combinations of algorithm methods. * - * +flag+ can be one of the following, other flags are available depending on + * _flag_ can be one of the following, other flags are available depending on * your OS. * * [All flags] 0xFFFF @@ -432,14 +433,13 @@ ossl_engine_set_default(VALUE self, VALUE flag) return Qtrue; } -/* Document-method: OpenSSL::Engine#ctrl_cmd - * +/* * call-seq: * engine.ctrl_cmd(command, value = nil) -> engine * - * Send the given +command+ to this engine. + * Sends the given _command_ to this engine. * - * Raises an EngineError if the +command+ fails. + * Raises an EngineError if the command fails. */ static VALUE ossl_engine_ctrl_cmd(int argc, VALUE *argv, VALUE self) @@ -469,7 +469,9 @@ ossl_engine_cmd_flag_to_name(int flag) } } -/* Document-method: OpenSSL::Engine#cmds +/* + * call-seq: + * engine.cmds -> [["name", "description", "flags"], ...] * * Returns an array of command definitions for the current engine */ @@ -495,9 +497,11 @@ ossl_engine_get_cmds(VALUE self) return ary; } -/* Document-method: OpenSSL::Engine#inspect +/* + * call-seq: + * engine.inspect -> string * - * Pretty print this engine + * Pretty prints this engine. */ static VALUE ossl_engine_inspect(VALUE self) diff --git a/ext/openssl/ossl_hmac.c b/ext/openssl/ossl_hmac.c index 270979ed..4e892b6c 100644 --- a/ext/openssl/ossl_hmac.c +++ b/ext/openssl/ossl_hmac.c @@ -135,7 +135,7 @@ ossl_hmac_copy(VALUE self, VALUE other) * call-seq: * hmac.update(string) -> self * - * Returns +self+ updated with the message to be authenticated. + * Returns _hmac_ updated with the message to be authenticated. * Can be called repeatedly with chunks of the message. * * === Example @@ -234,7 +234,7 @@ ossl_hmac_hexdigest(VALUE self) * call-seq: * hmac.reset -> self * - * Returns +self+ as it was when it was first initialized, with all processed + * Returns _hmac_ as it was when it was first initialized, with all processed * data cleared from it. * * === Example @@ -264,16 +264,16 @@ ossl_hmac_reset(VALUE self) * call-seq: * HMAC.digest(digest, key, data) -> aString * - * Returns the authentication code as a binary string. The +digest+ parameter - * must be an instance of OpenSSL::Digest. + * Returns the authentication code as a binary string. The _digest_ parameter + * specifies the digest algorithm to use. This may be a String representing + * the algorithm name or an instance of OpenSSL::Digest. * * === Example * * key = 'key' * data = 'The quick brown fox jumps over the lazy dog' - * digest = OpenSSL::Digest.new('sha1') * - * hmac = OpenSSL::HMAC.digest(digest, key, data) + * hmac = OpenSSL::HMAC.digest('sha1', key, data) * #=> "\xDE|\x9B\x85\xB8\xB7\x8A\xA6\xBC\x8Az6\xF7\n\x90p\x1C\x9D\xB4\xD9" * */ @@ -295,16 +295,16 @@ ossl_hmac_s_digest(VALUE klass, VALUE digest, VALUE key, VALUE data) * call-seq: * HMAC.hexdigest(digest, key, data) -> aString * - * Returns the authentication code as a hex-encoded string. The +digest+ - * parameter must be an instance of OpenSSL::Digest. + * Returns the authentication code as a hex-encoded string. The _digest_ + * parameter specifies the digest algorithm to use. This may be a String + * representing the algorithm name or an instance of OpenSSL::Digest. * * === Example * * key = 'key' * data = 'The quick brown fox jumps over the lazy dog' - * digest = OpenSSL::Digest.new('sha1') * - * hmac = OpenSSL::HMAC.hexdigest(digest, key, data) + * hmac = OpenSSL::HMAC.hexdigest('sha1', key, data) * #=> "de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9" * */ diff --git a/ext/openssl/ossl_ns_spki.c b/ext/openssl/ossl_ns_spki.c index 98f6552e..a64b3d3f 100644 --- a/ext/openssl/ossl_ns_spki.c +++ b/ext/openssl/ossl_ns_spki.c @@ -73,7 +73,7 @@ ossl_spki_alloc(VALUE klass) * SPKI.new([request]) => spki * * === Parameters - * * +request+ - optional raw request, either in PEM or DER format. + * * _request_ - optional raw request, either in PEM or DER format. */ static VALUE ossl_spki_initialize(int argc, VALUE *argv, VALUE self) @@ -198,7 +198,7 @@ ossl_spki_get_public_key(VALUE self) * spki.public_key = pub => pkey * * === Parameters - * * +pub+ - the public key to be set for this instance + * * _pub_ - the public key to be set for this instance * * Sets the public key to be associated with the SPKI, an instance of * OpenSSL::PKey. This should be the public key corresponding to the @@ -243,7 +243,7 @@ ossl_spki_get_challenge(VALUE self) * spki.challenge = str => string * * === Parameters - * * +str+ - the challenge string to be set for this instance + * * _str_ - the challenge string to be set for this instance * * Sets the challenge to be associated with the SPKI. May be used by the * server, e.g. to prevent replay. @@ -268,8 +268,8 @@ ossl_spki_set_challenge(VALUE self, VALUE str) * spki.sign(key, digest) => spki * * === Parameters - * * +key+ - the private key to be used for signing this instance - * * +digest+ - the digest to be used for signing this instance + * * _key_ - the private key to be used for signing this instance + * * _digest_ - the digest to be used for signing this instance * * To sign an SPKI, the private key corresponding to the public key set * for this instance should be used, in addition to a digest algorithm in @@ -298,7 +298,7 @@ ossl_spki_sign(VALUE self, VALUE key, VALUE digest) * spki.verify(key) => boolean * * === Parameters - * * +key+ - the public key to be used for verifying the SPKI signature + * * _key_ - the public key to be used for verifying the SPKI signature * * Returns +true+ if the signature is valid, +false+ otherwise. To verify an * SPKI, the public key contained within the SPKI should be used. diff --git a/ext/openssl/ossl_ocsp.c b/ext/openssl/ossl_ocsp.c index a8b3503d..cc36d21b 100644 --- a/ext/openssl/ossl_ocsp.c +++ b/ext/openssl/ossl_ocsp.c @@ -218,7 +218,7 @@ ossl_ocspreq_initialize_copy(VALUE self, VALUE other) * OpenSSL::OCSP::Request.new(request_der) -> request * * Creates a new OpenSSL::OCSP::Request. The request may be created empty or - * from a +request_der+ string. + * from a _request_der_ string. */ static VALUE @@ -248,7 +248,7 @@ ossl_ocspreq_initialize(int argc, VALUE *argv, VALUE self) * call-seq: * request.add_nonce(nonce = nil) -> request * - * Adds a +nonce+ to the OCSP request. If no nonce is given a random one will + * Adds a _nonce_ to the OCSP request. If no nonce is given a random one will * be generated. * * The nonce is used to prevent replay attacks but some servers do not support @@ -281,7 +281,7 @@ ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self) * call-seq: * request.check_nonce(response) -> result * - * Checks the nonce validity for this request and +response+. + * Checks the nonce validity for this request and _response_. * * The return value is one of the following: * @@ -291,7 +291,7 @@ ossl_ocspreq_add_nonce(int argc, VALUE *argv, VALUE self) * 2 :: nonces both absent. * 3 :: nonce present in response only. * - * For most responses, clients can check +result+ > 0. If a responder doesn't + * For most responses, clients can check _result_ > 0. If a responder doesn't * handle nonces result.nonzero? may be necessary. A result of * 0 is always an error. */ @@ -314,7 +314,7 @@ ossl_ocspreq_check_nonce(VALUE self, VALUE basic_resp) * call-seq: * request.add_certid(certificate_id) -> request * - * Adds +certificate_id+ to the request. + * Adds _certificate_id_ to the request. */ static VALUE @@ -371,17 +371,17 @@ ossl_ocspreq_get_certid(VALUE self) * call-seq: * request.sign(cert, key, certs = nil, flags = 0, digest = nil) -> self * - * Signs this OCSP request using +cert+, +key+ and optional +digest+. If - * +digest+ is not specified, SHA-1 is used. +certs+ is an optional Array of + * Signs this OCSP request using _cert_, _key_ and optional _digest_. If + * _digest_ is not specified, SHA-1 is used. _certs_ is an optional Array of * additional certificates which are included in the request in addition to - * the signer certificate. Note that if +certs+ is nil or not given, flag + * the signer certificate. Note that if _certs_ is +nil+ or not given, flag * OpenSSL::OCSP::NOCERTS is enabled. Pass an empty array to include only the * signer certificate. * - * +flags+ can be a bitwise OR of the following constants: + * _flags_ is a bitwise OR of the following constants: * * OpenSSL::OCSP::NOCERTS:: - * Don't include any certificates in the request. +certs+ will be ignored. + * Don't include any certificates in the request. _certs_ will be ignored. */ static VALUE ossl_ocspreq_sign(int argc, VALUE *argv, VALUE self) @@ -421,8 +421,8 @@ ossl_ocspreq_sign(int argc, VALUE *argv, VALUE self) * call-seq: * request.verify(certificates, store, flags = 0) -> true or false * - * Verifies this request using the given +certificates+ and +store+. - * +certificates+ is an array of OpenSSL::X509::Certificate, +store+ is an + * Verifies this request using the given _certificates_ and _store_. + * _certificates_ is an array of OpenSSL::X509::Certificate, _store_ is an * OpenSSL::X509::Store. */ @@ -479,7 +479,7 @@ ossl_ocspreq_to_der(VALUE self) /* call-seq: * OpenSSL::OCSP::Response.create(status, basic_response = nil) -> response * - * Creates an OpenSSL::OCSP::Response from +status+ and +basic_response+. + * Creates an OpenSSL::OCSP::Response from _status_ and _basic_response_. */ static VALUE @@ -539,7 +539,7 @@ ossl_ocspres_initialize_copy(VALUE self, VALUE other) * OpenSSL::OCSP::Response.new(response_der) -> response * * Creates a new OpenSSL::OCSP::Response. The response may be created empty or - * from a +response_der+ string. + * from a _response_der_ string. */ static VALUE @@ -693,7 +693,7 @@ ossl_ocspbres_initialize_copy(VALUE self, VALUE other) * call-seq: * OpenSSL::OCSP::BasicResponse.new(der_string = nil) -> basic_response * - * Creates a new BasicResponse. If +der_string+ is given, decodes +der_string+ + * Creates a new BasicResponse. If _der_string_ is given, decodes _der_string_ * as DER. */ @@ -724,7 +724,7 @@ ossl_ocspbres_initialize(int argc, VALUE *argv, VALUE self) * call-seq: * basic_response.copy_nonce(request) -> Integer * - * Copies the nonce from +request+ into this response. Returns 1 on success + * Copies the nonce from _request_ into this response. Returns 1 on success * and 0 on failure. */ @@ -746,7 +746,7 @@ ossl_ocspbres_copy_nonce(VALUE self, VALUE request) * call-seq: * basic_response.add_nonce(nonce = nil) * - * Adds +nonce+ to this response. If no nonce was provided a random nonce + * Adds _nonce_ to this response. If no nonce was provided a random nonce * will be added. */ @@ -792,26 +792,26 @@ add_status_convert_time(VALUE obj) * call-seq: * basic_response.add_status(certificate_id, status, reason, revocation_time, this_update, next_update, extensions) -> basic_response * - * Adds a certificate status for +certificate_id+. +status+ is the status, and + * Adds a certificate status for _certificate_id_. _status_ is the status, and * must be one of these: * * - OpenSSL::OCSP::V_CERTSTATUS_GOOD * - OpenSSL::OCSP::V_CERTSTATUS_REVOKED * - OpenSSL::OCSP::V_CERTSTATUS_UNKNOWN * - * +reason+ and +revocation_time+ can be given only when +status+ is - * OpenSSL::OCSP::V_CERTSTATUS_REVOKED. +reason+ describes the reason for the + * _reason_ and _revocation_time_ can be given only when _status_ is + * OpenSSL::OCSP::V_CERTSTATUS_REVOKED. _reason_ describes the reason for the * revocation, and must be one of OpenSSL::OCSP::REVOKED_STATUS_* constants. - * +revocation_time+ is the time when the certificate is revoked. + * _revocation_time_ is the time when the certificate is revoked. * - * +this_update+ and +next_update+ indicate the time at which ths status is + * _this_update_ and _next_update_ indicate the time at which ths status is * verified to be correct and the time at or before which newer information - * will be available, respectively. +next_update+ is optional. + * will be available, respectively. _next_update_ is optional. * - * +extensions+ is an Array of OpenSSL::X509::Extension to be included in the + * _extensions_ is an Array of OpenSSL::X509::Extension to be included in the * SingleResponse. This is also optional. * - * Note that the times, +revocation_time+, +this_update+ and +next_update+ + * Note that the times, _revocation_time_, _this_update_ and _next_update_ * can be specified in either of Integer or Time object. If they are Integer, it * is treated as the relative seconds from the current time. */ @@ -888,7 +888,7 @@ ossl_ocspbres_add_status(VALUE self, VALUE cid, VALUE status, * Returns an Array of statuses for this response. Each status contains a * CertificateId, the status (0 for good, 1 for revoked, 2 for unknown), the * reason for the status, the revocation time, the time of this update, the time - * for the next update and a list of OpenSSL::X509::Extensions. + * for the next update and a list of OpenSSL::X509::Extension. * * This should be superseded by BasicResponse#responses and #find_response that * return SingleResponse. @@ -977,7 +977,7 @@ ossl_ocspbres_get_responses(VALUE self) * call-seq: * basic_response.find_response(certificate_id) -> SingleResponse | nil * - * Returns a SingleResponse whose CertId matches with +certificate_id+, or nil + * Returns a SingleResponse whose CertId matches with _certificate_id_, or +nil+ * if this BasicResponse does not contain it. */ static VALUE @@ -1006,10 +1006,10 @@ ossl_ocspbres_find_response(VALUE self, VALUE target) * call-seq: * basic_response.sign(cert, key, certs = nil, flags = 0, digest = nil) -> self * - * Signs this OCSP response using the +cert+, +key+ and optional +digest+. This + * Signs this OCSP response using the _cert_, _key_ and optional _digest_. This * behaves in the similar way as OpenSSL::OCSP::Request#sign. * - * +flags+ can include: + * _flags_ can include: * OpenSSL::OCSP::NOCERTS:: don't include certificates * OpenSSL::OCSP::NOTIME:: don't set producedAt * OpenSSL::OCSP::RESPID_KEY:: use signer's public key hash as responderID @@ -1053,8 +1053,8 @@ ossl_ocspbres_sign(int argc, VALUE *argv, VALUE self) * call-seq: * basic_response.verify(certificates, store, flags = 0) -> true or false * - * Verifies the signature of the response using the given +certificates+ and - * +store+. This works in the similar way as OpenSSL::OCSP::Request#verify. + * Verifies the signature of the response using the given _certificates_ and + * _store_. This works in the similar way as OpenSSL::OCSP::Request#verify. */ static VALUE ossl_ocspbres_verify(int argc, VALUE *argv, VALUE self) @@ -1184,7 +1184,7 @@ ossl_ocspsres_alloc(VALUE klass) * call-seq: * OpenSSL::OCSP::SingleResponse.new(der_string) -> SingleResponse * - * Creates a new SingleResponse from +der_string+. + * Creates a new SingleResponse from _der_string_. */ static VALUE ossl_ocspsres_initialize(VALUE self, VALUE arg) @@ -1235,10 +1235,10 @@ ossl_ocspsres_initialize_copy(VALUE self, VALUE other) * * It is possible that the OCSP request takes a few seconds or the time is not * accurate. To avoid rejecting a valid response, this method allows the times - * to be within +nsec+ of the current time. + * to be within _nsec_ seconds of the current time. * * Some responders don't set the nextUpdate field. This may cause a very old - * response to be considered valid. The +maxsec+ parameter can be used to limit + * response to be considered valid. The _maxsec_ parameter can be used to limit * the age of responses. */ static VALUE @@ -1485,14 +1485,13 @@ ossl_ocspcid_initialize_copy(VALUE self, VALUE other) * OpenSSL::OCSP::CertificateId.new(subject, issuer, digest = nil) -> certificate_id * OpenSSL::OCSP::CertificateId.new(der_string) -> certificate_id * - * Creates a new OpenSSL::OCSP::CertificateId for the given +subject+ and - * +issuer+ X509 certificates. The +digest+ is used to compute the - * certificate ID and must be an OpenSSL::Digest instance. + * Creates a new OpenSSL::OCSP::CertificateId for the given _subject_ and + * _issuer_ X509 certificates. The _digest_ is a digest algorithm that is used + * to compute the hash values. This defaults to SHA-1. * * If only one argument is given, decodes it as DER representation of a * certificate ID. */ - static VALUE ossl_ocspcid_initialize(int argc, VALUE *argv, VALUE self) { @@ -1534,7 +1533,7 @@ ossl_ocspcid_initialize(int argc, VALUE *argv, VALUE self) * call-seq: * certificate_id.cmp(other) -> true or false * - * Compares this certificate id with +other+ and returns true if they are the + * Compares this certificate id with _other_ and returns +true+ if they are the * same. */ static VALUE @@ -1554,7 +1553,7 @@ ossl_ocspcid_cmp(VALUE self, VALUE other) * call-seq: * certificate_id.cmp_issuer(other) -> true or false * - * Compares this certificate id's issuer with +other+ and returns true if + * Compares this certificate id's issuer with _other_ and returns +true+ if * they are the same. */ diff --git a/ext/openssl/ossl_pkcs12.c b/ext/openssl/ossl_pkcs12.c index 0b9c7816..6a395cfa 100644 --- a/ext/openssl/ossl_pkcs12.c +++ b/ext/openssl/ossl_pkcs12.c @@ -89,20 +89,20 @@ ossl_pkcs12_initialize_copy(VALUE self, VALUE other) * PKCS12.create(pass, name, key, cert [, ca, [, key_pbe [, cert_pbe [, key_iter [, mac_iter [, keytype]]]]]]) * * === Parameters - * * +pass+ - string - * * +name+ - A string describing the key. - * * +key+ - Any PKey. - * * +cert+ - A X509::Certificate. + * * _pass_ - string + * * _name_ - A string describing the key. + * * _key_ - Any PKey. + * * _cert_ - A X509::Certificate. * * The public_key portion of the certificate must contain a valid public key. * * The not_before and not_after fields must be filled in. - * * +ca+ - An optional array of X509::Certificate's. - * * +key_pbe+ - string - * * +cert_pbe+ - string - * * +key_iter+ - integer - * * +mac_iter+ - integer - * * +keytype+ - An integer representing an MSIE specific extension. + * * _ca_ - An optional array of X509::Certificate's. + * * _key_pbe_ - string + * * _cert_pbe_ - string + * * _key_iter_ - integer + * * _mac_iter_ - integer + * * _keytype_ - An integer representing an MSIE specific extension. * - * Any optional arguments may be supplied as nil to preserve the OpenSSL defaults. + * Any optional arguments may be supplied as +nil+ to preserve the OpenSSL defaults. * * See the OpenSSL documentation for PKCS12_create(). */ @@ -161,8 +161,8 @@ ossl_pkcs12_s_create(int argc, VALUE *argv, VALUE self) * PKCS12.new(str, pass) -> pkcs12 * * === Parameters - * * +str+ - Must be a DER encoded PKCS12 string. - * * +pass+ - string + * * _str_ - Must be a DER encoded PKCS12 string. + * * _pass_ - string */ static VALUE ossl_pkcs12_initialize(int argc, VALUE *argv, VALUE self) diff --git a/ext/openssl/ossl_pkey.c b/ext/openssl/ossl_pkey.c index e161277d..47990319 100644 --- a/ext/openssl/ossl_pkey.c +++ b/ext/openssl/ossl_pkey.c @@ -123,15 +123,15 @@ ossl_pkey_new(EVP_PKEY *pkey) * OpenSSL::PKey.read(string [, pwd ]) -> PKey * OpenSSL::PKey.read(io [, pwd ]) -> PKey * - * Reads a DER or PEM encoded string from +string+ or +io+ and returns an + * Reads a DER or PEM encoded string from _string_ or _io_ and returns an * instance of the appropriate PKey class. * * === Parameters - * * +string+ is a DER- or PEM-encoded string containing an arbitrary private + * * _string+ is a DER- or PEM-encoded string containing an arbitrary private * or public key. - * * +io+ is an instance of +IO+ containing a DER- or PEM-encoded + * * _io_ is an instance of IO containing a DER- or PEM-encoded * arbitrary private or public key. - * * +pwd+ is an optional password in case +string+ or +file+ is an encrypted + * * _pwd_ is an optional password in case _string_ or _io_ is an encrypted * PEM resource. */ static VALUE @@ -259,7 +259,7 @@ ossl_pkey_alloc(VALUE klass) * PKeyClass.new -> self * * Because PKey is an abstract class, actually calling this method explicitly - * will raise a +NotImplementedError+. + * will raise a NotImplementedError. */ static VALUE ossl_pkey_initialize(VALUE self) @@ -274,10 +274,10 @@ ossl_pkey_initialize(VALUE self) * call-seq: * pkey.sign(digest, data) -> String * - * To sign the +String+ +data+, +digest+, an instance of OpenSSL::Digest, must - * be provided. The return value is again a +String+ containing the signature. + * To sign the String _data_, _digest_, an instance of OpenSSL::Digest, must + * be provided. The return value is again a String containing the signature. * A PKeyError is raised should errors occur. - * Any previous state of the +Digest+ instance is irrelevant to the signature + * Any previous state of the Digest instance is irrelevant to the signature * outcome, the digest instance is reset to its initial state during the * operation. * @@ -326,12 +326,12 @@ ossl_pkey_sign(VALUE self, VALUE digest, VALUE data) * call-seq: * pkey.verify(digest, signature, data) -> String * - * To verify the +String+ +signature+, +digest+, an instance of + * To verify the String _signature_, _digest_, an instance of * OpenSSL::Digest, must be provided to re-compute the message digest of the - * original +data+, also a +String+. The return value is +true+ if the + * original _data_, also a String. The return value is +true+ if the * signature is valid, +false+ otherwise. A PKeyError is raised should errors * occur. - * Any previous state of the +Digest+ instance is irrelevant to the validation + * Any previous state of the Digest instance is irrelevant to the validation * outcome, the digest instance is reset to its initial state during the * operation. * diff --git a/ext/openssl/ossl_pkey_dh.c b/ext/openssl/ossl_pkey_dh.c index dd85b7b9..48e898b5 100644 --- a/ext/openssl/ossl_pkey_dh.c +++ b/ext/openssl/ossl_pkey_dh.c @@ -150,8 +150,8 @@ dh_generate(int size, int gen) * components alike. * * === Parameters - * * +size+ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure. - * * +generator+ is a small number > 1, typically 2 or 5. + * * _size_ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure. + * * _generator_ is a small number > 1, typically 2 or 5. * */ static VALUE @@ -181,15 +181,15 @@ ossl_dh_s_generate(int argc, VALUE *argv, VALUE klass) * DH.new(size [, generator]) -> dh * * Either generates a DH instance from scratch or by reading already existing - * DH parameters from +string+. Note that when reading a DH instance from + * DH parameters from _string_. Note that when reading a DH instance from * data that was encoded from a DH instance by using DH#to_pem or DH#to_der * the result will *not* contain a public/private key pair yet. This needs to * be generated using DH#generate_key! first. * * === Parameters - * * +size+ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure. - * * +generator+ is a small number > 1, typically 2 or 5. - * * +string+ contains the DER or PEM encoded key. + * * _size_ is an integer representing the desired key size. Keys smaller than 1024 bits should be considered insecure. + * * _generator_ is a small number > 1, typically 2 or 5. + * * _string_ contains the DER or PEM encoded key. * * === Examples * DH.new # -> dh @@ -436,7 +436,7 @@ ossl_dh_to_text(VALUE self) * dh.public_key -> aDH * * Returns a new DH instance that carries just the public information, i.e. - * the prime +p+ and the generator +g+, but no public/private key yet. Such + * the prime _p_ and the generator _g_, but no public/private key yet. Such * a pair may be generated using DH#generate_key!. The "public key" needed * for a key exchange with DH#compute_key is considered as per-session * information and may be retrieved with DH#pub_key once a key pair has @@ -526,7 +526,7 @@ ossl_dh_generate_key(VALUE self) * See DH_compute_key() for further information. * * === Parameters - * * +pub_bn+ is a OpenSSL::BN, *not* the DH instance returned by + * * _pub_bn_ is a OpenSSL::BN, *not* the DH instance returned by * DH#public_key as that contains the DH parameters only. */ static VALUE @@ -557,7 +557,7 @@ ossl_dh_compute_key(VALUE self, VALUE pub) * call-seq: * dh.set_pqg(p, q, g) -> self * - * Sets +p+, +q+, +g+ for the DH instance. + * Sets _p_, _q_, _g_ to the DH instance. */ OSSL_PKEY_BN_DEF3(dh, DH, pqg, p, q, g) /* @@ -565,7 +565,7 @@ OSSL_PKEY_BN_DEF3(dh, DH, pqg, p, q, g) * call-seq: * dh.set_key(pub_key, priv_key) -> self * - * Sets +pub_key+ and +priv_key+ for the DH instance. +priv_key+ may be nil. + * Sets _pub_key_ and _priv_key_ for the DH instance. _priv_key_ may be +nil+. */ OSSL_PKEY_BN_DEF2(dh, DH, key, pub_key, priv_key) diff --git a/ext/openssl/ossl_pkey_dsa.c b/ext/openssl/ossl_pkey_dsa.c index b21abc42..53d5c8d9 100644 --- a/ext/openssl/ossl_pkey_dsa.c +++ b/ext/openssl/ossl_pkey_dsa.c @@ -172,7 +172,7 @@ dsa_generate(int size) * from scratch. * * === Parameters - * * +size+ is an integer representing the desired key size. + * * _size_ is an integer representing the desired key size. * */ static VALUE @@ -195,12 +195,12 @@ ossl_dsa_s_generate(VALUE klass, VALUE size) * DSA.new(size) -> dsa * DSA.new(string [, pass]) -> dsa * - * Creates a new DSA instance by reading an existing key from +string+. + * Creates a new DSA instance by reading an existing key from _string_. * * === Parameters - * * +size+ is an integer representing the desired key size. - * * +string+ contains a DER or PEM encoded key. - * * +pass+ is a string that contains an optional password. + * * _size_ is an integer representing the desired key size. + * * _string_ contains a DER or PEM encoded key. + * * _pass_ is a string that contains an optional password. * * === Examples * DSA.new -> dsa @@ -329,8 +329,8 @@ ossl_dsa_is_private(VALUE self) * Encodes this DSA to its PEM encoding. * * === Parameters - * * +cipher+ is an OpenSSL::Cipher. - * * +password+ is a string containing your password. + * * _cipher_ is an OpenSSL::Cipher. + * * _password_ is a string containing your password. * * === Examples * DSA.to_pem -> aString @@ -503,12 +503,12 @@ ossl_dsa_to_public_key(VALUE self) * call-seq: * dsa.syssign(string) -> aString * - * Computes and returns the DSA signature of +string+, where +string+ is + * Computes and returns the DSA signature of _string_, where _string_ is * expected to be an already-computed message digest of the original input * data. The signature is issued using the private key of this DSA instance. * * === Parameters - * * +string+ is a message digest of the original input data to be signed + * * _string_ is a message digest of the original input data to be signed. * * === Example * dsa = OpenSSL::PKey::DSA.new(2048) @@ -549,11 +549,11 @@ ossl_dsa_sign(VALUE self, VALUE data) * dsa.sysverify(digest, sig) -> true | false * * Verifies whether the signature is valid given the message digest input. It - * does so by validating +sig+ using the public key of this DSA instance. + * does so by validating _sig_ using the public key of this DSA instance. * * === Parameters - * * +digest+ is a message digest of the original input data to be signed - * * +sig+ is a DSA signature value + * * _digest_ is a message digest of the original input data to be signed + * * _sig_ is a DSA signature value * * === Example * dsa = OpenSSL::PKey::DSA.new(2048) @@ -590,7 +590,7 @@ ossl_dsa_verify(VALUE self, VALUE digest, VALUE sig) * call-seq: * dsa.set_pqg(p, q, g) -> self * - * Sets +p+, +q+, +g+ for the DSA instance. + * Sets _p_, _q_, _g_ to the DSA instance. */ OSSL_PKEY_BN_DEF3(dsa, DSA, pqg, p, q, g) /* @@ -598,7 +598,7 @@ OSSL_PKEY_BN_DEF3(dsa, DSA, pqg, p, q, g) * call-seq: * dsa.set_key(pub_key, priv_key) -> self * - * Sets +pub_key+ and +priv_key+ for the DSA instance. +priv_key+ may be nil. + * Sets _pub_key_ and _priv_key_ for the DSA instance. _priv_key_ may be +nil+. */ OSSL_PKEY_BN_DEF2(dsa, DSA, key, pub_key, priv_key) diff --git a/ext/openssl/ossl_pkey_ec.c b/ext/openssl/ossl_pkey_ec.c index ce347516..f0e27461 100644 --- a/ext/openssl/ossl_pkey_ec.c +++ b/ext/openssl/ossl_pkey_ec.c @@ -275,7 +275,7 @@ ossl_ec_key_initialize_copy(VALUE self, VALUE other) * key.group => group * * Returns the EC::Group that the key is associated with. Modifying the returned - * group does not affect +key+. + * group does not affect _key_. */ static VALUE ossl_ec_key_get_group(VALUE self) @@ -296,7 +296,7 @@ ossl_ec_key_get_group(VALUE self) * key.group = group * * Sets the EC::Group for the key. The group structure is internally copied so - * modifition to +group+ after assigning to a key has no effect on the key. + * modifition to _group_ after assigning to a key has no effect on the key. */ static VALUE ossl_ec_key_set_group(VALUE self, VALUE group_v) @@ -502,8 +502,8 @@ static VALUE ossl_ec_key_to_string(VALUE self, VALUE ciph, VALUE pass, int forma * key.export([cipher, pass_phrase]) => String * key.to_pem([cipher, pass_phrase]) => String * - * Outputs the EC key in PEM encoding. If +cipher+ and +pass_phrase+ are given - * they will be used to encrypt the key. +cipher+ must be an OpenSSL::Cipher + * Outputs the EC key in PEM encoding. If _cipher_ and _pass_phrase_ are given + * they will be used to encrypt the key. _cipher_ must be an OpenSSL::Cipher * instance. Note that encryption will only be effective for a private key, * public keys will always be encoded in plain text. */ @@ -724,7 +724,7 @@ ec_group_new(const EC_GROUP *group) * * Creates a new EC::Group object. * - * +ec_method+ is a symbol that represents an EC_METHOD. Currently the following + * _ec_method_ is a symbol that represents an EC_METHOD. Currently the following * are supported: * * * :GFp_simple @@ -862,8 +862,8 @@ ossl_ec_group_initialize_copy(VALUE self, VALUE other) * group1.eql?(group2) => true | false * group1 == group2 => true | false * - * Returns true if the two groups use the same curve and have the same - * parameters, false otherwise. + * Returns +true+ if the two groups use the same curve and have the same + * parameters, +false+ otherwise. */ static VALUE ossl_ec_group_eql(VALUE a, VALUE b) { @@ -903,8 +903,8 @@ static VALUE ossl_ec_group_get_generator(VALUE self) * call-seq: * group.set_generator(generator, order, cofactor) => self * - * Sets the curve parameters. +generator+ must be an instance of EC::Point that - * is on the curve. +order+ and +cofactor+ are integers. + * Sets the curve parameters. _generator_ must be an instance of EC::Point that + * is on the curve. _order_ and _cofactor_ are integers. * * See the OpenSSL documentation for EC_GROUP_set_generator() */ @@ -1127,14 +1127,14 @@ parse_point_conversion_form_symbol(VALUE sym) * * Sets the form how EC::Point data is encoded as ASN.1 as defined in X9.62. * - * +format+ can be one of these: + * _format_ can be one of these: * - * :compressed:: + * +:compressed+:: * Encoded as z||x, where z is an octet indicating which solution of the * equation y is. z will be 0x02 or 0x03. - * :uncompressed:: + * +:uncompressed+:: * Encoded as z||x||y, where z is an octet 0x04. - * :hybrid:: + * +:hybrid+:: * Encodes as z||x||y, where z is an octet indicating which solution of the * equation y is. z will be 0x06 or 0x07. * @@ -1558,7 +1558,7 @@ static VALUE ossl_ec_point_set_to_infinity(VALUE self) * point.to_bn(conversion_form = nil) => OpenSSL::BN * * Convert the EC point into an octet string and store in an OpenSSL::BN. If - * +conversion_form+ is given, the point data is converted using the specified + * _conversion_form_ is given, the point data is converted using the specified * form. If not given, the default form set in the EC::Group object is used. * * See also EC::Point#point_conversion_form=. @@ -1597,12 +1597,12 @@ ossl_ec_point_to_bn(int argc, VALUE *argv, VALUE self) * Performs elliptic curve point multiplication. * * The first form calculates bn1 * point + bn2 * G, where +G+ is the - * generator of the group of +point+. +bn2+ may be ommitted, and in that case, + * generator of the group of _point_. _bn2_ may be ommitted, and in that case, * the result is just bn1 * point. * * The second form calculates bns[0] * point + bns[1] * points[0] + ... - * + bns[-1] * points[-1] + bn2 * G. +bn2+ may be ommitted. +bns+ must be - * an array of OpenSSL::BN. +points+ must be an array of + * + bns[-1] * points[-1] + bn2 * G. _bn2_ may be ommitted. _bns_ must be + * an array of OpenSSL::BN. _points_ must be an array of * OpenSSL::PKey::EC::Point. Please note that points[0] is not * multiplied by bns[0], but bns[1]. */ diff --git a/ext/openssl/ossl_pkey_rsa.c b/ext/openssl/ossl_pkey_rsa.c index cea228d6..59c12f5c 100644 --- a/ext/openssl/ossl_pkey_rsa.c +++ b/ext/openssl/ossl_pkey_rsa.c @@ -172,8 +172,8 @@ rsa_generate(int size, unsigned long exp) * RSA.generate(size) => RSA instance * RSA.generate(size, exponent) => RSA instance * - * Generates an RSA keypair. +size+ is an integer representing the desired key - * size. Keys smaller than 1024 should be considered insecure. +exponent+ is + * Generates an RSA keypair. _size_ is an integer representing the desired key + * size. Keys smaller than 1024 should be considered insecure. _exponent_ is * an odd number normally 3, 17, or 65537. */ static VALUE @@ -203,12 +203,12 @@ ossl_rsa_s_generate(int argc, VALUE *argv, VALUE klass) * RSA.new(encoded_key) => RSA instance * RSA.new(encoded_key, pass_phrase) => RSA instance * - * Generates or loads an RSA keypair. If an integer +key_size+ is given it + * Generates or loads an RSA keypair. If an integer _key_size_ is given it * represents the desired key size. Keys less than 1024 bits should be * considered insecure. * - * A key can instead be loaded from an +encoded_key+ which must be PEM or DER - * encoded. A +pass_phrase+ can be used to decrypt the key. If none is given + * A key can instead be loaded from an _encoded_key_ which must be PEM or DER + * encoded. A _pass_phrase_ can be used to decrypt the key. If none is given * OpenSSL will prompt for the pass phrase. * * = Examples @@ -295,7 +295,7 @@ ossl_rsa_initialize_copy(VALUE self, VALUE other) * call-seq: * rsa.public? => true * - * The return value is always true since every private key is also a public + * The return value is always +true+ since every private key is also a public * key. */ static VALUE @@ -333,8 +333,8 @@ ossl_rsa_is_private(VALUE self) * rsa.to_pem([cipher, pass_phrase]) => PEM-format String * rsa.to_s([cipher, pass_phrase]) => PEM-format String * - * Outputs this keypair in PEM encoding. If +cipher+ and +pass_phrase+ are - * given they will be used to encrypt the key. +cipher+ must be an + * Outputs this keypair in PEM encoding. If _cipher_ and _pass_phrase_ are + * given they will be used to encrypt the key. _cipher_ must be an * OpenSSL::Cipher instance. */ static VALUE @@ -409,7 +409,7 @@ ossl_rsa_to_der(VALUE self) * rsa.public_encrypt(string) => String * rsa.public_encrypt(string, padding) => String * - * Encrypt +string+ with the public key. +padding+ defaults to PKCS1_PADDING. + * Encrypt _string_ with the public key. _padding_ defaults to PKCS1_PADDING. * The encrypted string output can be decrypted using #private_decrypt. */ static VALUE @@ -441,8 +441,8 @@ ossl_rsa_public_encrypt(int argc, VALUE *argv, VALUE self) * rsa.public_decrypt(string) => String * rsa.public_decrypt(string, padding) => String * - * Decrypt +string+, which has been encrypted with the private key, with the - * public key. +padding+ defaults to PKCS1_PADDING. + * Decrypt _string_, which has been encrypted with the private key, with the + * public key. _padding_ defaults to PKCS1_PADDING. */ static VALUE ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self) @@ -473,7 +473,7 @@ ossl_rsa_public_decrypt(int argc, VALUE *argv, VALUE self) * rsa.private_encrypt(string) => String * rsa.private_encrypt(string, padding) => String * - * Encrypt +string+ with the private key. +padding+ defaults to PKCS1_PADDING. + * Encrypt _string_ with the private key. _padding_ defaults to PKCS1_PADDING. * The encrypted string output can be decrypted using #public_decrypt. */ static VALUE @@ -507,8 +507,8 @@ ossl_rsa_private_encrypt(int argc, VALUE *argv, VALUE self) * rsa.private_decrypt(string) => String * rsa.private_decrypt(string, padding) => String * - * Decrypt +string+, which has been encrypted with the public key, with the - * private key. +padding+ defaults to PKCS1_PADDING. + * Decrypt _string_, which has been encrypted with the public key, with the + * private key. _padding_ defaults to PKCS1_PADDING. */ static VALUE ossl_rsa_private_decrypt(int argc, VALUE *argv, VALUE self) @@ -659,7 +659,7 @@ ossl_rsa_blinding_off(VALUE self) * call-seq: * rsa.set_key(n, e, d) -> self * - * Sets +n+, +e+, +d+ for the RSA instance. + * Sets _n_, _e_, _d_ for the RSA instance. */ OSSL_PKEY_BN_DEF3(rsa, RSA, key, n, e, d) /* @@ -667,7 +667,7 @@ OSSL_PKEY_BN_DEF3(rsa, RSA, key, n, e, d) * call-seq: * rsa.set_factors(p, q) -> self * - * Sets +p+, +q+ for the RSA instance. + * Sets _p_, _q_ for the RSA instance. */ OSSL_PKEY_BN_DEF2(rsa, RSA, factors, p, q) /* @@ -675,7 +675,7 @@ OSSL_PKEY_BN_DEF2(rsa, RSA, factors, p, q) * call-seq: * rsa.set_crt_params(dmp1, dmq1, iqmp) -> self * - * Sets +dmp1+, +dmq1+, +iqmp+ for the RSA instance. They are calculated by + * Sets _dmp1_, _dmq1_, _iqmp_ for the RSA instance. They are calculated by * d mod (p - 1), d mod (q - 1) and q^(-1) mod p * respectively. */ diff --git a/ext/openssl/ossl_rand.c b/ext/openssl/ossl_rand.c index 688c525a..c9585706 100644 --- a/ext/openssl/ossl_rand.c +++ b/ext/openssl/ossl_rand.c @@ -16,7 +16,7 @@ VALUE eRandomError; * call-seq: * seed(str) -> str * - * ::seed is equivalent to ::add where +entropy+ is length of +str+. + * ::seed is equivalent to ::add where _entropy_ is length of _str_. */ static VALUE ossl_rand_seed(VALUE self, VALUE str) @@ -31,15 +31,15 @@ ossl_rand_seed(VALUE self, VALUE str) * call-seq: * add(str, entropy) -> self * - * Mixes the bytes from +str+ into the Pseudo Random Number Generator(PRNG) + * Mixes the bytes from _str_ into the Pseudo Random Number Generator(PRNG) * state. * - * Thus, if the data from +str+ are unpredictable to an adversary, this + * Thus, if the data from _str_ are unpredictable to an adversary, this * increases the uncertainty about the state and makes the PRNG output less * predictable. * - * The +entropy+ argument is (the lower bound of) an estimate of how much - * randomness is contained in +str+, measured in bytes. + * The _entropy_ argument is (the lower bound of) an estimate of how much + * randomness is contained in _str_, measured in bytes. * * === Example * @@ -62,7 +62,7 @@ ossl_rand_add(VALUE self, VALUE str, VALUE entropy) * call-seq: * load_random_file(filename) -> true * - * Reads bytes from +filename+ and adds them to the PRNG. + * Reads bytes from _filename_ and adds them to the PRNG. */ static VALUE ossl_rand_load_file(VALUE self, VALUE filename) @@ -79,7 +79,7 @@ ossl_rand_load_file(VALUE self, VALUE filename) * call-seq: * write_random_file(filename) -> true * - * Writes a number of random generated bytes (currently 1024) to +filename+ + * Writes a number of random generated bytes (currently 1024) to _filename_ * which can be used to initialize the PRNG by calling ::load_random_file in a * later session. */ @@ -98,7 +98,7 @@ ossl_rand_write_file(VALUE self, VALUE filename) * call-seq: * random_bytes(length) -> string * - * Generates +string+ with +length+ number of cryptographically strong + * Generates a String with _length_ number of cryptographically strong * pseudo-random bytes. * * === Example @@ -129,7 +129,7 @@ ossl_rand_bytes(VALUE self, VALUE len) * call-seq: * pseudo_bytes(length) -> string * - * Generates +string+ with +length+ number of pseudo-random bytes. + * Generates a String with _length_ number of pseudo-random bytes. * * Pseudo-random byte sequences generated by ::pseudo_bytes will be unique if * they are of sufficient length, but are not necessarily unpredictable. @@ -176,9 +176,9 @@ ossl_rand_egd(VALUE self, VALUE filename) * call-seq: * egd_bytes(filename, length) -> true * - * Queries the entropy gathering daemon EGD on socket path given by +filename+. + * Queries the entropy gathering daemon EGD on socket path given by _filename_. * - * Fetches +length+ number of bytes and uses ::add to seed the OpenSSL built-in + * Fetches _length_ number of bytes and uses ::add to seed the OpenSSL built-in * PRNG. */ static VALUE @@ -199,7 +199,7 @@ ossl_rand_egd_bytes(VALUE self, VALUE filename, VALUE len) * call-seq: * status? => true | false * - * Return true if the PRNG has been seeded with enough data, false otherwise. + * Return +true+ if the PRNG has been seeded with enough data, +false+ otherwise. */ static VALUE ossl_rand_status(VALUE self) diff --git a/ext/openssl/ossl_ssl.c b/ext/openssl/ossl_ssl.c index 033e0346..4d674aa6 100644 --- a/ext/openssl/ossl_ssl.c +++ b/ext/openssl/ossl_ssl.c @@ -1186,7 +1186,7 @@ ossl_sslctx_set_security_level(VALUE self, VALUE value) * call-seq: * ctx.session_add(session) -> true | false * - * Adds +session+ to the session cache. + * Adds _session_ to the session cache. */ static VALUE ossl_sslctx_session_add(VALUE self, VALUE arg) @@ -1204,7 +1204,7 @@ ossl_sslctx_session_add(VALUE self, VALUE arg) * call-seq: * ctx.session_remove(session) -> true | false * - * Removes +session+ from the session cache. + * Removes _session_ from the session cache. */ static VALUE ossl_sslctx_session_remove(VALUE self, VALUE arg) @@ -1340,9 +1340,9 @@ ossl_sslctx_get_session_cache_stats(VALUE self) /* * call-seq: - * ctx.flush_sessions(time | nil) -> self + * ctx.flush_sessions(time) -> self * - * Removes sessions in the internal cache that have expired at +time+. + * Removes sessions in the internal cache that have expired at _time_. */ static VALUE ossl_sslctx_flush_sessions(int argc, VALUE *argv, VALUE self) @@ -1404,10 +1404,10 @@ ossl_ssl_s_alloc(VALUE klass) * SSLSocket.new(io) => aSSLSocket * SSLSocket.new(io, ctx) => aSSLSocket * - * Creates a new SSL socket from +io+ which must be a real IO object (not an + * Creates a new SSL socket from _io_ which must be a real IO object (not an * IO-like object that responds to read/write). * - * If +ctx+ is provided the SSL Sockets initial params will be taken from + * If _ctx_ is provided the SSL Sockets initial params will be taken from * the context. * * The OpenSSL::Buffering module provides additional IO methods. @@ -1757,7 +1757,7 @@ ossl_ssl_read_internal(int argc, VALUE *argv, VALUE self, int nonblock) * ssl.sysread(length) => string * ssl.sysread(length, buffer) => buffer * - * Reads +length+ bytes from the SSL connection. If a pre-allocated +buffer+ + * Reads _length_ bytes from the SSL connection. If a pre-allocated _buffer_ * is provided the data will be written into it. */ static VALUE @@ -1776,7 +1776,7 @@ ossl_ssl_read(int argc, VALUE *argv, VALUE self) * block. If "exception: false" is passed, this method returns a symbol of * :wait_readable, :wait_writable, or nil, rather than raising an exception. * - * Reads +length+ bytes from the SSL connection. If a pre-allocated +buffer+ + * Reads _length_ bytes from the SSL connection. If a pre-allocated _buffer_ * is provided the data will be written into it. */ static VALUE @@ -1846,7 +1846,7 @@ ossl_ssl_write_internal(VALUE self, VALUE str, VALUE opts) * call-seq: * ssl.syswrite(string) => Integer * - * Writes +string+ to the SSL connection. + * Writes _string_ to the SSL connection. */ static VALUE ossl_ssl_write(VALUE self, VALUE str) @@ -1858,7 +1858,7 @@ ossl_ssl_write(VALUE self, VALUE str) * call-seq: * ssl.syswrite_nonblock(string) => Integer * - * Writes +string+ to the SSL connection in a non-blocking manner. Raises an + * Writes _string_ to the SSL connection in a non-blocking manner. Raises an * SSLError if writing would block. */ static VALUE @@ -2063,7 +2063,7 @@ ossl_ssl_pending(VALUE self) * call-seq: * ssl.session_reused? -> true | false * - * Returns true if a reused session was negotiated during the handshake. + * Returns +true+ if a reused session was negotiated during the handshake. */ static VALUE ossl_ssl_session_reused(VALUE self) @@ -2282,7 +2282,7 @@ Init_ossl_ssl(void) * This module contains configuration information about the SSL extension, * for example if socket support is enabled, or the host name TLS extension * is enabled. Constants in this module will always be defined, but contain - * `true` or `false` values depending on the configuration of your OpenSSL + * +true+ or +false+ values depending on the configuration of your OpenSSL * installation. */ mSSLExtConfig = rb_define_module_under(mOSSL, "ExtConfig"); @@ -2366,12 +2366,12 @@ Init_ossl_ssl(void) * A callback for additional certificate verification. The callback is * invoked for each certificate in the chain. * - * The callback is invoked with two values. +preverify_ok+ indicates - * indicates if the verification was passed (true) or not (false). - * +store_context+ is an OpenSSL::X509::StoreContext containing the + * The callback is invoked with two values. _preverify_ok_ indicates + * indicates if the verification was passed (+true+) or not (+false+). + * _store_context_ is an OpenSSL::X509::StoreContext containing the * context used for certificate verification. * - * If the callback returns false, the chain verification is immediately + * If the callback returns +false+, the chain verification is immediately * stopped and a bad_certificate alert is then sent. */ rb_attr(cSSLContext, rb_intern("verify_callback"), 1, 1, Qfalse); @@ -2438,7 +2438,7 @@ Init_ossl_ssl(void) /* * A callback invoked when a new session was negotiated. * - * The callback is invoked with an SSLSocket. If false is returned the + * The callback is invoked with an SSLSocket. If +false+ is returned the * session will be removed from the internal cache. */ rb_attr(cSSLContext, rb_intern("session_new_cb"), 1, 1, Qfalse); diff --git a/ext/openssl/ossl_ssl_session.c b/ext/openssl/ossl_ssl_session.c index fefbf28b..11287ad1 100644 --- a/ext/openssl/ossl_ssl_session.c +++ b/ext/openssl/ossl_ssl_session.c @@ -113,7 +113,7 @@ ossl_SSL_SESSION_cmp(const SSL_SESSION *a, const SSL_SESSION *b) * call-seq: * session1 == session2 -> boolean * - * Returns true if the two Session is the same, false if not. + * Returns +true+ if the two Session is the same, +false+ if not. */ static VALUE ossl_ssl_session_eq(VALUE val1, VALUE val2) { diff --git a/ext/openssl/ossl_x509cert.c b/ext/openssl/ossl_x509cert.c index cecc3ca0..00bce40c 100644 --- a/ext/openssl/ossl_x509cert.c +++ b/ext/openssl/ossl_x509cert.c @@ -586,7 +586,8 @@ ossl_x509_sign(VALUE self, VALUE key, VALUE digest) * call-seq: * cert.verify(key) => true | false * - * Checks that cert signature is made with PRIVversion of this PUBLIC 'key' + * Verifies the signature of the certificate, with the public key _key_. _key_ + * must be an instance of OpenSSL::PKey. */ static VALUE ossl_x509_verify(VALUE self, VALUE key) @@ -610,9 +611,10 @@ ossl_x509_verify(VALUE self, VALUE key) /* * call-seq: - * cert.check_private_key(key) + * cert.check_private_key(key) -> true | false * - * Checks if 'key' is PRIV key for this cert + * Returns +true+ if _key_ is the corresponding private key to the Subject + * Public Key Information, +false+ otherwise. */ static VALUE ossl_x509_check_private_key(VALUE self, VALUE key) diff --git a/ext/openssl/ossl_x509ext.c b/ext/openssl/ossl_x509ext.c index b92b0786..ad810e4d 100644 --- a/ext/openssl/ossl_x509ext.c +++ b/ext/openssl/ossl_x509ext.c @@ -263,15 +263,15 @@ ossl_x509ext_alloc(VALUE klass) /* * call-seq: - * OpenSSL::X509::Extension.new asn1 - * OpenSSL::X509::Extension.new name, value - * OpenSSL::X509::Extension.new name, value, critical + * OpenSSL::X509::Extension.new(der) + * OpenSSL::X509::Extension.new(oid, value) + * OpenSSL::X509::Extension.new(oid, value, critical) * * Creates an X509 extension. * - * The extension may be created from +asn1+ data or from an extension +name+ - * and +value+. The +name+ may be either an OID or an extension name. If - * +critical+ is true the extension is marked critical. + * The extension may be created from _der_ data or from an extension _oid_ + * and _value_. The _oid_ may be either an OID or an extension name. If + * _critical_ is +true+ the extension is marked critical. */ static VALUE ossl_x509ext_initialize(int argc, VALUE *argv, VALUE self) diff --git a/ext/openssl/ossl_x509name.c b/ext/openssl/ossl_x509name.c index a10ae2c3..20f811ea 100644 --- a/ext/openssl/ossl_x509name.c +++ b/ext/openssl/ossl_x509name.c @@ -135,15 +135,15 @@ ossl_x509name_init_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, args)) * * 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+. + * 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 + * See add_entry for a description of the _distinguished_name_ Array's * contents */ static VALUE @@ -204,7 +204,7 @@ ossl_x509name_initialize_copy(VALUE self, VALUE other) * call-seq: * name.add_entry(oid, value [, type]) => self * - * Adds a new entry with the given +oid+ and +value+ to this name. The +oid+ + * 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 @@ -251,15 +251,19 @@ ossl_x509name_to_s_old(VALUE self) /* * call-seq: - * name.to_s => string - * name.to_s(flags) => string + * name.to_s -> string + * name.to_s(format) -> string * - * Returns this name as a Distinguished Name string. +flags+ may be one of: + * Returns a String representation of the Distinguished Name. _format_ is + * one of: * * * OpenSSL::X509::Name::COMPAT * * OpenSSL::X509::Name::RFC2253 * * OpenSSL::X509::Name::ONELINE * * OpenSSL::X509::Name::MULTILINE + * + * If _format_ is omitted, the largely broken and traditional OpenSSL format + * is used. */ static VALUE ossl_x509name_to_s(int argc, VALUE *argv, VALUE self) @@ -345,11 +349,11 @@ ossl_x509name_cmp0(VALUE self, VALUE other) /* * call-seq: - * name.cmp other => integer - * name.<=> other => integer + * name.cmp(other) -> -1 | 0 | 1 + * name <=> other -> -1 | 0 | 1 * - * Compares this Name with +other+ and returns 0 if they are the same and -1 or - * +1 if they are greater or less than each other respectively. + * Compares this Name with _other_ and returns +0+ if they are the same and +-1+ + * or ++1+ if they are greater or less than each other respectively. */ static VALUE ossl_x509name_cmp(VALUE self, VALUE other) @@ -365,9 +369,9 @@ ossl_x509name_cmp(VALUE self, VALUE other) /* * call-seq: - * name.eql? other => boolean + * name.eql?(other) -> true | false * - * Returns true if +name+ and +other+ refer to the same hash key. + * Returns true if _name_ and _other_ refer to the same hash key. */ static VALUE ossl_x509name_eql(VALUE self, VALUE other) diff --git a/ext/openssl/ossl_x509store.c b/ext/openssl/ossl_x509store.c index eb81e0d4..3ea6ea14 100644 --- a/ext/openssl/ossl_x509store.c +++ b/ext/openssl/ossl_x509store.c @@ -242,9 +242,9 @@ ossl_x509store_initialize(int argc, VALUE *argv, VALUE self) /* * call-seq: - * store.flags = flag + * store.flags = flags * - * Sets +flag+ to the Store. +flag+ consists of zero or more of the constants + * Sets _flags_ to the Store. _flags_ consists of zero or more of the constants * defined in with name V_FLAG_* or'ed together. */ static VALUE @@ -263,7 +263,7 @@ ossl_x509store_set_flags(VALUE self, VALUE flags) * call-seq: * store.purpose = purpose * - * Sets the store's purpose to +purpose+. If specified, the verifications on + * Sets the store's purpose to _purpose_. If specified, the verifications on * the store will check every untrusted certificate's extensions are consistent * with the purpose. The purpose is specified by constants: * @@ -322,8 +322,9 @@ ossl_x509store_set_time(VALUE self, VALUE time) * call-seq: * store.add_file(file) -> self * - * Adds the certificates in +file+ to the certificate store. The +file+ can - * contain multiple PEM-encoded certificates. + * Adds the certificates in _file_ to the certificate store. _file_ is the path + * to the file, and the file contains one or more certificates in PEM format + * concatenated together. */ static VALUE ossl_x509store_add_file(VALUE self, VALUE file) @@ -350,7 +351,7 @@ ossl_x509store_add_file(VALUE self, VALUE file) * call-seq: * store.add_path(path) -> self * - * Adds +path+ as the hash dir to be looked up by the store. + * Adds _path_ as the hash dir to be looked up by the store. */ static VALUE ossl_x509store_add_path(VALUE self, VALUE dir) @@ -377,7 +378,7 @@ ossl_x509store_add_path(VALUE self, VALUE dir) * call-seq: * store.set_default_paths * - * Configures +store+ to look up CA certificates from the system default + * Configures _store_ to look up CA certificates from the system default * certificate store as needed basis. The location of the store can usually be * determined by: * @@ -401,7 +402,7 @@ ossl_x509store_set_default_paths(VALUE self) * call-seq: * store.add_cert(cert) * - * Adds the OpenSSL::X509::Certificate +cert+ to the certificate store. + * Adds the OpenSSL::X509::Certificate _cert_ to the certificate store. */ static VALUE ossl_x509store_add_cert(VALUE self, VALUE arg) @@ -422,7 +423,7 @@ ossl_x509store_add_cert(VALUE self, VALUE arg) * call-seq: * store.add_crl(crl) -> self * - * Adds the OpenSSL::X509::CRL +crl+ to the store. + * Adds the OpenSSL::X509::CRL _crl_ to the store. */ static VALUE ossl_x509store_add_crl(VALUE self, VALUE arg) @@ -447,15 +448,15 @@ static VALUE ossl_x509stctx_get_chain(VALUE); * call-seq: * store.verify(cert, chain = nil) -> true | false * - * Performs a certificate verification on the OpenSSL::X509::Certificate +cert+. + * Performs a certificate verification on the OpenSSL::X509::Certificate _cert_. * - * +chain+ can be an array of OpenSSL::X509::Certificate that is used to + * _chain_ can be an array of OpenSSL::X509::Certificate that is used to * construct the certificate chain. * * If a block is given, it overrides the callback set by #verify_callback=. * * After finishing the verification, the error information can be retrieved by - * #error, #error_string, and the resuting complete certificate chain can be + * #error, #error_string, and the resulting complete certificate chain can be * retrieved by #chain. */ static VALUE -- cgit v1.2.3