Back to Contents

The CryptoKey class

Summary:

See also: The Genero Web Services XML Library

Syntax

The CryptoKey class provides methods to manipulate HMAC, symmetric and asymmetric keys needed for signing, verifying, encrypting and decrypting XML documents or document fragments. It follows the XML-Signature and XML-Encryption specifications.

The status is set to zero after a successful method call.

Syntax

xml.CryptoKey
 

Methods

Creation methods

Class Methods
Name Description
xml.CryptoKey.Create(
  url STRING )
   RETURNING xml.CryptoKey 		Constructor of an empty CryptoKey object depending on a url, where url defines a key identifier according to the XML-Signature and XML-Encryption specification.

Returns a CryptoKey object or NULL.

Throws an exception in case of errors, and updates status with an error code.

xml.CryptoKey.CreateFromNode(
  url STRING ,
  node xml.DomNode)
   RETURNING xml.CryptoKey 		Constructor of a new CryptoKey object depending on a url and from a XML node, according to the XML-Signature and XML-Encryption specification; where url defines a key identifier restricted to PUBLIC/PRIVATE keys, and node is an ELEMENT node whose local name is either:
  • DSAKeyValue or RSAKeyValue and belonging to the XML-Signature namespace http://www.w3.org/2000/09/xmldsig#
  • RSAKeyPair and belonging to the XKMS 2.0 namespace http://www.w3.org/2002/03/xkms#.
Returns a CryptoKey object or NULL.

If the local name is RSAKeyValue or RSAKeyPair, the URL must be a RSA key. If the local name is DSAKeyValue, the URL must be a DSA key.

Throws an exception in case of errors, and updates status with an error code.

xml.CryptoKey.CreateDerivedKey(
  url STRING )
   RETURNING xml.CryptoKey 		Constructor of an empty CryptoKey object intended to be derived before use, and depending on a url; where url defines a key identifier according to the XML-Signature and XML-Encryption specification.

Returns a CryptoKey object or NULL.

Only symmetric and HMAC keys can be derived.

Throws an exception in case of errors, and updates status with an error code.

Back to the top

Access methods

Object Methods
Name Description
getUrl()
   RETURNING STRING 		Returns the key identifier as an URL as defined in the XML-Signature and XML-Encryption specification.

Throws an exception in case of errors, and updates status with an error code.

getType()
   RETURNING STRING		 Returns the type of key.

Throws an exception in case of errors, and updates status with an error code.

getUsage()
   RETURNING STRING		 Returns the usage of the key.

Throws an exception in case of errors, and updates status with an error code.

getSize()
   RETURNING INTEGER		 Returns the size of the key in bits.

Throws an exception in case of errors, and updates status with an error code.

compareTo(
 key xml.CryptoKey)
   RETURNING INTEGER		 Compares this CryptoKey object to the given one, and returns true if they are identical.

It verifies if the keys URL, type, size, usage and value are the same. In other words, two identical keys will produce the same encryption cipher.

Note: The key features are not taken into account during comparison.

Throws an exception in case of errors, and updates status with an error code.

Back to the top

Modify methods

Object Methods
Name Description
setKey(
  key STRING )		 Defines the value of a HMAC or Symmetric key.

The value can be a password and must be of the size corresponding to the key identifier.

Throws an exception in case of errors, and updates status with an error code.

generateKey(
  size INTEGER )		 Generates a random key of given size (in bits).

For symmetric keys, the size is fixed by the key identifier, and you can't change it. The only authorized values are the real key size or NULL.

Throws an exception in case of errors, and updates status with an error code.

deriveKey(
  method  STRING ,
  label   STRING ,
  seed    STRING ,
  created STRING ,
  offset  INTEGER ,
  size    INTEGER )		 Derives the symmetric or HMAC CryptoKey object using given method identifier and concatenating the optional label, the mandatory seed value and the optional created date as initial random value; where size defines the number of bytes of the resulting derived key, offset the number of bytes the resulting octet stream must be shifted to obtain the derived key and seed a valid Base64 string representing a random binary data you can obtain with the CreateRandomString() helper method.

If it is a symmetric key, the size can be 0, or must match the original key according to key identifier.

See derived keys for more details.

Throws an exception in case of errors, and updates status with an error code.

Back to the top

Load and save methods

Object Methods
Name Description
loadPEM(
  file STRING ) 		Loads an asymmetric DSA or RSA key from a file in PEM format, where file is the filename or an entry in the FGLPROFILE file.

If the DSA or RSA private key is protected with a password, the recommended way is to unprotect it with the openssl tool and to put the key file on a restricted file system. However, you can use a script or the fglpass agent to provide the password to the application.

Throws an exception in case of errors, and updates status with an error code.

loadDER(
  file STRING ) 		Loads an asymmetric DSA or RSA key from a file in DER format, where file is the filename or an entry in the FGLPROFILE file.

If the DSA or RSA private key is protected with a password, the recommended way is to unprotect it with the openssl tool and to put the key file on a restricted file system. However, you can use a script or the fglpass agent to provide the password to the application.

Throws an exception in case of errors, and updates status with an error code.

loadBIN(
  file STRING ) 		Loads a symmetric or HMAC key from a file in raw format, where file is the filename or an entry in the FGLPROFILE file.

Raw format means that the data in the file are read without any transformation, and will be stored as it in the key.

For instance, if you file contains hello, it has the same effect as calling setKey() with hello as parameter.

Throws an exception in case of errors, and updates status with an error code.

savePublic()
  RETURNING xml.DomDocument		 Saves the public part of an asymmetric RSA or DSA CryptoKey object into a XML document according to the XML-Signature specification for DSA and RSA key value.

See also the RetrievalMethod feature.

Throws an exception in case of errors, and updates status with an error code.

savePrivate()
  RETURNING xml.DomDocument		 Saves the private part of an asymmetric RSA CryptoKey object into a XML document according to the XKMS 2.0 specification.

Throws an exception in case of errors, and updates status with an error code.

saveToString()
   RETURNING STRING 		Saves the CryptoKey object into a BASE64 string format.

Throws an exception in case of errors, and updates status with an error code.

loadPublic(
  xml xml.DomDocument)		 Loads the public asymmetric RSA or DSA key in the given XML document into the public part of this CryptoKey object, according to the XML-Signature specification for DSA and RSA key value.

Throws an exception in case of errors, and updates status with an error code.

loadPrivate(
  xml xml.DomDocument)		 Loads the private asymmetric RSA key in the given XML document into the private part of this CryptoKey object, according to the XKMS 2.0 specification.

Throws an exception in case of errors, and updates status with an error code.

loadFromString(
  str STRING) 		Loads the given key in BASE64 string format into this CryptoKey object.

Throws an exception in case of errors, and updates status with an error code.

Back to the top

Feature methods

Object Methods
Name Description
setFeature(
  feature STRING,
  value STRING) 		Sets or resets the given feature for this CryptoKey object.

Throws an exception in case of errors, and updates status with an error code.

getFeature(
  feature STRING)
   RETURNING STRING		 Returns the value of the given feature for this CryptoKey object, or NULL if the feature is not set.

Throws an exception in case of errors, and updates status with an error code.

Back to the top

Supported kind of keys

Identifier Description Usage Type
http://www.w3.org/2000/09/xmldsig#dsa-sha1 Asymmetric DSA key with SHA1 for signature purposes.
Uses a private DSA key for signature and needs an associated public DSA key or X509 certificate containing it, to verify it.
See specification for details.		 SIGNATURE PUBLIC or PRIVATE
http://www.w3.org/2000/09/xmldsig#rsa-sha1 Asymmetric RSA key with SHA1 for signature purposes.
Uses a private RSA key for signature and needs an associated public RSA key or X509 certificate containing it, to verify it.
See specification for details.		 SIGNATURE PUBLIC or PRIVATE
http://www.w3.org/2000/09/xmldsig#hmac-sha1 Message Authentication Code key with SHA1 for signature purposes.
Uses a same password for signature and to verify it, and key size is free.
See specification for details. 		SIGNATURE HMAC
http://www.w3.org/2001/04/xmlenc#aes128-cbc Symmectric AES128 key for encryption purposes.
Uses a common key of 128bits for encrypting and decrypting XML documents.
See specification for details. 		ENCRYPTION SYMMETRIC
http://www.w3.org/2001/04/xmlenc#aes192-cbc Symmetric AES192 key for encryption purposes.
Uses a common key of 192bits for encrypting and decrypting XML documents.
See specification for details.		 ENCRYPTION SYMMETRIC
http://www.w3.org/2001/04/xmlenc#aes256-cbc Symmetric AES256 key for encryption purposes.
Uses a common key of 256bits for encrypting and decrypting XML documents.
See specification for details. 		ENCRYPTION SYMMETRIC
http://www.w3.org/2001/04/xmlenc#tripledes-cbc Symmetric TripleDes key for encryption purposes.
Uses a common key of 192bits for encrypting and decrypting XML documents.
See specification for details. 		ENCRYPTION SYMMETRIC
http://www.w3.org/2001/04/xmlenc#kw-aes128 Symmetric AES128 key wrap for key encryption purposes.
Uses a common key of 128bits for encrypting and decrypting a symmetric key.
See specification for details. 		KEY
ENCRYPTION		 SYMMETRIC
http://www.w3.org/2001/04/xmlenc#kw-aes192 Symmetric AES192 key wrap for key encryption purposes.
Uses a common key of 192bits for encrypting and decrypting a symmetric key.
See specification for details. 		KEY
ENCRYPTION		 SYMMETRIC
http://www.w3.org/2001/04/xmlenc#kw-aes256 Symmetric AES256 key wrap for key encryption purposes.
Uses a common key of 256bits for encrypting and decrypting a symmetric key.
See specification for details. 		KEY
ENCRYPTION		 SYMMETRIC
http://www.w3.org/2001/04/xmlenc#kw-tripledes Symmetric TripleDes key wrap for key encryption purposes.
Uses a common key of 192bits for encrypting and decrypting a symmetric key.
See specification for details. 		KEY
ENCRYPTION		 SYMMETRIC
http://www.w3.org/2001/04/xmlenc#rsa-1_5 Asymmetric RSA key for key encryption purposes.
Uses a public RSA key or a X509 certificate containing it to encrypt a symmetric key, and needs the associated private RSA key to decrypt it.
See specification for details. 		KEY
ENCRYPTION		 PUBLIC or PRIVATE
http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p Asymmetric RSA key for key encryption purposes.
Uses a public RSA key or a X509 certificate containing it to encrypt a symmetric key, and needs the associated private RSA key to decrypt it.
See specification for details. 		KEY ENCRYPTION PUBLIC or PRIVATE

Back to the top

Derived keys

Key derivation is used on symmetric or HMAC keys to avoid the direct usage of a shared secret password in secured operations. If two parties share a secret password that is successfully hacked by a third party, any future operation becomes unsecure, and the initial two parties do not even realize that their exchanges are unsafe. However, if a different password based on that shared secret password is used for each new secured operation, even if one operation is compromised, it will only unsecure that operation, but not other operations.

The derivation consists of applying an algorithm with some additional inputs (such as a random seed value) to a password in order to obtain another password that is then used in one secured operation. Of course, the algorithm and its additional inputs must also be shared to enable the computation of the same derived key by someone that is intended to decrypt the message.

Notice also that passwords are often only composed of alpha-numeric characters that eases a bit more the job of a hacker, whereas a derived key is composed of any binary data produced by the algorithm used for the derivation.

Method Description
http://schemas.xmlsoap.org/ws/2005/02/sc/dk/p_sha1 Only algorithm supported. See specification for details.

Back to the top

CryptoKey Features

Feature Description
KeyName
(See specification for details)		 Defines or returns whether a user-defined key name is added during a XML signature or encryption in order to identify it to other applications, or by the key store.

The default value is NULL, meaning that no key name is used.

KeyValue
(See specification for details)		 Defines or returns whether the public part of the asymmetric key is added during a XML signature or encryption.

Only for RSA and DSA keys.

The default value is FALSE, meaning that no key value is used.
RetrievalMethod
(See specification for details)		 Defines or returns the URL where the XML form of
  • a DSA or RSA public key will be set during a XML signature, and loaded during a XML verification process.
  • a RSA public key will be set and used to encrypt a XML node during XML encryption
  • a symmetric key with encryption uage will be used to encrypt a XML node or decrypt it back
The default value is NULL, meaning that no retrieval method is used.

The XML form of a DSA or RSA public key can be obtain by the savePublic() method.

The XML form of a symmetric key can be obtain by the encryptKey() method

Back to the top

Examples

Example 1 : Loading an asymmetric RSA key

01 IMPORT xml
02 
03 MAIN
04   DEFINE key xml.CryptoKey
05   LET key = xml.CryptoKey.Create("http://www.w3.org/2001/04/xmlenc#rsa-1_5")
06   TRY
07   CALL key.loadPEM("RSA1024Key.pem") 
08     CALL key.setFeature("KeyName","MyRsaKey") 
09     DISPLAY "Key size (in bits) : ",key.getSize() # displays 1024 (bits)
10     DISPLAY "Key type : ",key.getType() # displays PRIVATE or PUBLIC
11     DISPLAY "Key usage : ",key.getUsage() # displays KEYENCRYPTION
12   CATCH
13     DISPLAY "Unable to load key :",STATUS
14   END TRY 
15 END MAIN

Example 2 : Generating a symmetric AES256 key

01 IMPORT xml
02 
03 MAIN
04  DEFINE key xml.CryptoKey
05  LET key = xml.CryptoKey.Create("http://www.w3.org/2001/04/xmlenc#aes256-cbc")
06   TRY
07     CALL key.generateKey(NULL) 
08     DISPLAY "Key size (in bits) : ",key.getSize() # displays 256 (bits)
09     DISPLAY "Key type : ",key.getType() # displays SYMMETRIC
10     DISPLAY "Key usage : ",key.getUsage() # displays ENCRYPTION
11   CATCH
12     DISPLAY "Unable to generate key :",STATUS
13   END TRY 
14 END MAIN

Example 3 : Setting a HMAC key

01 IMPORT xml
02 
03 MAIN
04   DEFINE key xml.CryptoKey
05   LET key = xml.CryptoKey.Create("http://www.w3.org/2000/09/xmldsig#hmac-sha1")
06   TRY
07     CALL key.setKey("secretpassword") 
08     DISPLAY "Key size (in bits) : ",key.getSize() # displays 112 (size of secretpassword in bits)
09     DISPLAY "Key type : ",key.getType() # displays HMAC
10     DISPLAY "Key usage : ",key.getUsage() # displays SIGNATURE
11   CATCH
12     DISPLAY "Unable to set key :",STATUS
13   END TRY 
14 END MAIN

Example 4 : Deriving a HMAC key

01 IMPORT xml
02 IMPORT com
03 
04 MAIN
05   DEFINE key xml.CryptoKey
06   DEFINE seedBase64 STRING # will contain a random binary data encoded in Base64
07   LET key = xml.CryptoKey.CreateDerivedKey("http://www.w3.org/2000/09/xmldsig#hmac-sha1")
08   TRY
09     CALL key.setKey("secretpassword") 
10     # Creates a random 24 bytes long binary data encoded into a Base64 form string
11     LET seedBase64 = com.Util.CreateRandomString(24)
12     # Derives the 14 bytes long "secretpassword" into a 64 bytes long key
13     # from a random 24 bytes long seed value and shifting the resulting key from 255 bytes
14     CALL key.deriveKey("http://schemas.xmlsoap.org/ws/2005/02/sc/dk/p_sha1",NULL,seedBase64,NULL,255,64) 
15     DISPLAY "Key size (in bits) : ",key.getSize() # displays 512 (size of 'secretpassword' derivation in bits)
16     # Note: from now key is derived and can be used in any encryption or signature function
17   CATCH
18      DISPLAY "Unable to derive key :",STATUS
19   END TRY 
20 END MAIN

Note: All keys in PEM or DER format were created with the OpenSSL tool.

Back to the top