NAME

 Net::SSL::CipherSuites - functions for getting, filtering lists of SSL/TLS cipher suites

VERSION

Version 0.8, $Revision: 626 $

SYNOPSIS

   # empty cipher list
   my $ciphers = Net::SSL::CipherSuites->new(); 
   # fill by Bettercrypto A list
   $ciphers->new_by_tags("bettercrypto_a");

   # or directly
   my $ciphers = Net::SSL::CipherSuites->new_by_tags("bettercrypto_a"); 

   # All ciphers
   my $ciphers = Net::SSL::CipherSuites->new_with_all; 
   
   # by name
   my $ciphers = Net::SSL::CipherSuites->new_by_name(qw(NULL NULL_WITH_NULL_NULL RSA_WITH_NULL_SHA256)); 
   
   # add ciphers by tag
   $ciphers->add( Net::SSL::CipherSuites->new_by_tags("SSLv3") );
   
   # remove ciphers from list (e.g. used or other tag)
   $ciphers->remove( Net::SSL::CipherSuites->by_tags( qw(weak WEAK LOW) ) );
   
   # Important: make cipher list unique, 
   # because by selecting via name/tag/.... there may be duplicates!
   # even with only one Tag there MAY be duplicates
   $ciphers->unique;
   
   # 
   ....

Werte pro Cipher-Suite:

  cipher suite name       zb ECDHE-ECDSA-AES256-GCM-SHA384  
  cipher suite value      zb ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  
  constant                as hex string 
  
  openssl score           HIGH, MEDIUM, LOW, WAEK (0.9.8)
  sslaudit score          sslaudit.ini
  BSI score
  bettercrypto score
  our score               anhand: andere scores, insbes. BSI, Bits, Algorithmen, ...
  
  protocol version
  Encryption Algorithm    None, AES, AESCCM, AESGCM, CAMELLIA, DES, 3DES, FZA, IDEA, RC4, RC2, SEED
  Key Size                bits
  MAC Algorithm           MD5, SHA1, SHA256, SHA384, AEAD
  Authentication          None, DSS, RSA, ECDH, ECDSA, KRB5, PSK
  Key Exchange            DH, ECDH, ECDH/ECDSA, RSA, KRB5, PSK, SRP
  
  source                  rfc123

DESCRIPTION

The purpose of this module is to collect and manage as many SSL/TLS cipher suites as possible. It manages lists of cipher suites, can filter all by tags or names, can add new cipher suites to an cipher list object or delete suites from the list. Cipher(lists) can be converted in their binary constant, so that they can be used in a SSL/TLS handshake and vice versa.

For best performance (and memory usage) the cipher lists are managed as ordinary hashrefs, they are not objects. Only the cipher lists are objects.

CIPHER STRINGS FROM BROWSERS X notes!

Checked at cc.dcsec.uni-hannover.de:

Safari:

Version: 3.1 / TLSv1

Ciphers: ff,c024,c023,c00a,c009,c008,c028,c027,c014,c013,c012,c026,c025,c005,c004,c003,c02a,c029,c00f,c00e,c00d,6b,67,39,33,16,3d,3c,35,2f,0a,c007,c011,c002,c00c,05,04

Extensions: 0000,000a,000b,000d,3374

UA: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/601.2.7 (KHTML, like Gecko) Version/9.0.1 Safari/601.2.7

Firefox:

Version: 3.1 / TLSv1

Ciphers: c02b,c02f,c00a,c009,c013,c014,33,39,2f,35,0a

Extensions: 0000,ff01,000a,000b,0023,3374,0010,0005,000d

UA: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:41.0) Gecko/20100101 Firefox/41.0

Chrome:

Version: 3.1 / TLSv1

Ciphers: c02b,c02f,9e,cc14,cc13,cc15,c00a,c014,39,c009,c013,33,9c,35,2f,0a

Extensions: ff01,0000,0017,0023,000d,0005,3374,0012,0010,7550,000b,000a

UA: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36

METHODS

new_with_all

Selects all cipher suites available

->new_by_name($name1, $name2, @names, ...)

Selects ciphers by their name (short or long).

Duplicates are not removed!

->new_by_tag(@tags)

Returns all Ciphers, selected by one or more Tags. The list of tags can be one or more arrays or arrayrefs or any combination.

Duplicates are not removed!

->new_by_code(@codes)

Returns all Ciphers, selected by one or more codes as hex string.

Duplicates are not removed!

->unique()

Removes duplicates from the cipher suites.

Old Version: Important: this sub changes the order of the ciphers. They are in more or less random order!

New: order not changed

cipher_spec( [ $version ] )

Returns the SSL/TLS cipher_spec for the (internally stored) cipher list. Returns the cipher_spec as binary string. 2 bytes per cipher, compatible with SSLv3 and TLS, NOT SSLv2.

If optional argument is < 0x0300 (SSLv3), conitnues with cipher_spec_sslv2.

Dies, if there is a SSLv2 only cipher in SSLv3+ mode.

cipher_spec_sslv2

Returns the SSL/TLS cipher_spec for the internal cipher list as SSLv2 cipher spec.

Returns the cipher_spec as binary string. 3 bytes per cipher, compatible with SSLv2, SSLv3/TLS.

new_by_cipher_spec($cipher_spec);

Returns the SSL/TLS ciphers for a binary cipher_spec.

Parameter: the cipher_spec as binary string, 3 bytes per cipher.

Returns a list of ciphers in list context, and an arrayref in scalar context.

new_by_cipher_spec_sslv2($cipher_spec);

The same as "new_by_cipher_spec", but with a SSLv2 cipher spec (3 bytes per cipher!)

->add( @ciphers | $ciphers_ref | $obj )

Takes one or more ciphers, refernces to a list of ciphers or cipher objects and adds them to the ciphers.

->remove( @ciphers | $ciphers_ref | $obj )

Removes one or more ciphers from the ciphers list. Ciphers are identified by the code, so if there are duplicate ciphers by code with different name etc, they are removed too.

Ans all duplicates are removed too.

Takes one or more ciphers, refernces to a list of ciphers or cipher objects.

->remove_first_by_code( $code | @codes )

Removes the first cipher from the cipherlist, which matches a $code. Each code from the list is only removed one time!

# TODO: Check performance for most common cases!

->remove_all_by_code( $code | @codes )

Removes all ciphers from the cipherlist, which matches a $code.

->order_by_code

Orders the cipher list by the code.

TLS Ciphers (2 bytes) are prefixed with 00.

->names

Get all cipher Names.

In List context: returns an array of all names.

In Scalar context: returns all names, separated with space.

->split_into_parts( [ $ssl_version ] [, $max_bytes] )

Some (broken) SSL/TLS implementations recognize only a limited number of cipher suites in the handshake. To handle this, this method creates an array of CipherSuite-Objects with parts of the original list.

Optional parameter $ssl_version is the SSL-Version string; default is $SSL3 and up.

Optional parameter $max_bytes is the maximum number of bytes of a resulting cipher_spec; default: 146.

TODO: which default max bytes?