Public/Private Key

Module Implementation: OpenSSLCryptoInterfacePKEY

This module implements various public/private key algorithms such as asymmetric encrypt/decrypt, key agreement, digital signatures and enveloping.

Note: Internal classes are italicized and will only contain a short description.

See the class-side examples in the OpenSSLPublicPrivateKeyExamples class for additional usage detail.

PKey

OpenSSLEnvelopeCtx: Internal state object used during open/seal digital enveloping.

OSSslDH: OSSslDHKey internal pkey struct accessor.

OSSslDSA: OSSslDSAKey internal pkey struct accessor.

OSSslRSA: OSSslRSAKey internal pkey struct accessor.

OSSslEC: OSSslECKey internal pkey struct accessor.

OSSslECBuiltinCurve: OpenSSL preconstructed curves

OSSslECGroup: Eliptic Curve group definition

OSSslECMethod: Eliptic Curve Methods supported by OpenSSL

OSSslECMethod: Point on an Eliptic Curve

OSSslPKey

Abstract superclass of all Asymmetric public key algorithms. It contains most of the functionality relating to public/private key storage and conversion.

Class methods: Creation

createNewFromBytes: aStringOrByteArray

Read the Private/Public key from a DER or PEM encoded data.

Arguments:

aStringOrByteArray - data in <String> or <ByteArray> form

Answers:

<OSSslPKey subclass> - Pkey instance

<OpenSSLError compatible error> - error object

 

createNewFromBytes: aStringOrByteArray password: aPassword

Read the Private/Public key from a DER or PEM encoded data. If the data is password protected, then aPassword will be a String.If not password is required, then aPassword will be nil.

Arguments:

aStringOrByteArray - data in <String> or <ByteArray> form

aPassword - Optional password <String>. Could be nil for no passwd.

Answers:

<OSSslPKey subclass> - Pkey instance

<OpenSSLError compatible error> - error object

 

createNewFromFile: aFilename

Read the Private/Public key from a DER or PEM encoded file with full path name aFilename.

Arguments:

aFilename - full path name to file

Answers:

<OSSslPKey subclass> - Pkey instance

<OpenSSLError compatible error> - error object

 

createNewFromFile: aFilename password: aPassword

Read the Private/Public key from a DER or PEM encoded file with full path name aFilename. If the data is password protected, then aPassword will be a String. If not password is required, then aPassword will be nil.

Arguments:

aFilename - full path name to file

aPassword - Optional password <String>. Could be nil for no passwd.

Answers:

<OSSslPKey subclass> - Pkey instance

<OpenSSLError compatible error> - error object

 

Instance methods: Accessing

size

Answers the maximum size of a signature in bytes.

Answers:

<Integer>

 

Instance methods: API - Digital Signatures

sign: aByteObject with: anOSSslDigest

Answers a digital signature for aByteObject using the digest anOSSslDigest and this pkey

Note: The Pkey algorithm must support digital signatures. If not, an error object is answered.

Arguments:

aByteObject - a collection of bytes THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)

anOSSslDigest - <OSSslDigest> message digest algorithm

Answers:

<ByteArray> digital signature

 

verify: signature from: aByteObject with: anOSSslDigest

Answers a <Boolean> indicating if the digital signature for aByteObject using the digest anOSSslDigest and this pkey is verified

Note: The Pkey algorithm must support digital signatures. If not, an error object is answered.

Arguments:

aByteObject - a collection of bytes THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)

anOSSslDigest - <OSSslDigest> message digest algorithm

Answers:

<Boolean> true if the digital signature is verified

 

Instance methods: Conversion

asDER

Answer this PKey encoded in DER format as a <ByteArray>.

Answers:

<ByteArray>

 

asPEM

Answer this PKey encoded in PEM format as a <String>.

Answers:

< String>

 

asPublicDER

DER-encode just the public portion of this key.

Answers:

<ByteArray>

 

asPublicKey

Answer a new managed instance of just the public key portion of this pkey.

Answers:

< OSSslPkey> public key

 

asPublicPEM

Export just the public portion of this key to PEM format.

Answers:

< String>

 

Instance methods: Key Generation

generateKey

Generates new random keys using existing key parameters.

Answers:

< OSSslPKey subclass>

 

generateKey:aKeyParameter

Generates new keys for the PKey using the @aKeyParameter.

Arguments:

aKeyParameter - @see the concrete PKey's class>>generateKey:for: for a description of what @aKeyParameter is

Answers:

< OSSslPKey subclass> self

 

Instance methods: Printing

printDEROn: aStreamOrBIO

Write the PKey in DER format to aStreamOrBIO. This allows Smalltalk stream to be used as well.

Arguments:

aStreamOrBIO - <WriteStream or compatible | OSSslBIO>

Answers:

<WriteStream or compatible | OSSslBIO>

 

printPEMOn: aStreamOrBIO

Write the PKey in PEM format to aStreamOrBIO. This allows Smalltalk stream to be used as well.

Arguments:

aStreamOrBIO - <WriteStream or compatible | OSSslBIO>

Answers:

<WriteStream or compatible | OSSslBIO>

 

printPEMOn: aStreamOrBIO cipher: aCipher password: aPassword

Write the PKey in PEM format to aStreamOrBIO using the supplied aCipher and aPassword. If only one of the chipher or password is supplied...they both will be ignored. The caller must supply a cipher AND password or neither. This allows Smalltalk stream to be used as well.

Arguments:

aStreamOrBIO - <WriteStream or compatible | OSSslBIO>

aCipher - <OSSslCipher> or nil

aPassword - <String> or nil.

Answers:

<WriteStream or compatible | OSSslBIO>

 

printPublicDEROn: aStreamOrBIO

Write the Public key version of the PKey in DER format to aStreamOrBIO. This allows Smalltalk stream to be used as well.

Arguments:

aStreamOrBIO - <WriteStream or compatible | OSSslBIO>

Answers:

<WriteStream or compatible | OSSslBIO>

 

printPublicPEMOn: aStreamOrBIO

Write the Public key version of the PKey in PEM format to aStreamOrBIO. This allows Smalltalk stream to be used as well.

Arguments:

aStreamOrBIO - <WriteStream or compatible | OSSslBIO>

Answers:

<WriteStream or compatible | OSSslBIO>

 

Instance methods: Testing

isPrivateKey

Answer true if this is a private key.

Answers:

<Boolean>

 

isPublicKey

Answer true if this HAS a public key.

Answers:

< Boolean>

 

supportsDigitalSignatures

Answer true if this PKey algorithm supports digital signatures.

Answers:

<Boolean>

 

supportsKeyTransport

Answer true if this PKey algorithm supports key transport (i.e. digital envelopes.)

Answers:

< Boolean>

 

supportsProbabilisticSignatureScheme

Answers true if this PKey algorithm supports PSS

Answers:

< Boolean>

 

OSSslDHKey

Implements the Diffie-Hellman key agreement protocol.

Class methods: Creation

createNew: bitsOrBitsAndGenerator

Create a new instance of the DH Key. This is done by generating the DH key using the arguments provided. The argument bitsOrBitsAndGenerator can be:

1. An <Association> with the key <Integer> length in BITS (safe prime to be generated) and a value <Integer> generator which is a small number > 1, typically 2 or 5.

2. An <Integer> to just define the bits...this is shorthand for a nil exponent described above.

Arguments:

bitsOrBitsAndGenerator - <Association> described above

Answers:

< OSSslDHKey> - DH key

 

Instance methods: Accessing

g

Answer the public g generator value as an <OSSslBigNumber>. This is a member of the Diffie-Hellman parameters.

Answers:

< OSSslBigNumber>

 

p

Answer the public p prime value as an <OSSslBigNumber>. This is a member of the Diffie-Hellman parameters

Answers:

< OSSslBigNumber>

 

publicValue

Answer the public key value of this DH key as an <OSSslBigNumber>. If no public key value is set, it will be generated first.

Answers:

< OSSslBigNumber>

 

Instance methods: API - Key Agreement

computeKey: publicValue

Computes and answers the shared secret from the private DH value and the other party's public value and stores it in shared secret.

Arguments:

publicValue - <Integer | OSSslBigNumber | OSSslAsn1Integer>

Answers:

<ByteArray> shared secret

 

generateKey

Performs the first step of a Diffie-Hellman key exchange by generating private and public DH values. By calling self>>computeKey, these are combined with the other party's public value to compute the shared key.

Answers:

< OSSslDHKey> - self

<OpenSSLError> - error object

 

publicValue

Answer the public key value of this DH key as an <OSSslBigNumber>. If no public key value is set, it will be generated first.

Answers:

< OSSslBigNumber>

 

Instance methods: Conversion

asPublicKey

Answer a new managed instance of just the DH public key.

Answers:

< OSSslDHKey> DH public key

 

Instance methods: Testing

isPrivateKey

Answer true if this is a private key.

Answers:

<Boolean>

 

isPublicKey

Answer true if this HAS a public key.

Answers:

< Boolean>

 

supportsDigitalSignatures

Diffie-Hellman is a key-agreement protocol.

It does not support digital signatures

Answers:

<Boolean> - false

 

supportsKeyTransport

Diffie-Hellman does not support key transport.

Answers:

< Boolean> - false

 

supportsProbabilisticSignatureScheme

Diffie-Hellman does not support PSS

Answers:

< Boolean> - false

 

 

Instance methods: Validation

check

Validates Diffie-Hellman parameters. Check that p is a safe prime, and that g is a suitable generator. In the case of an error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or DH_NOT_SUITABLE_GENERATOR are set in *codes. DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be checked, i.e. it does not equal 2 or 5.

Answers:

<Boolean> true if dh params pass validation

 

checkWithErrorCode

Validates Diffie-Hellman parameters. Check that p is a safe prime, and that g is a suitable generator. In the case of an error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or DH_NOT_SUITABLE_GENERATOR are set in *codes. DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be checked, i.e. it does not equal 2 or 5.

Answers:

<True> true if dh params are validated

<OpenSSLError> if the check failed with the reason placed in the OpenSSLError>>errorCode

OSSslDSAKey

Digital Signature Algorithm.

Class methods: Creation

createNew: bitsOrBitsAnd20ByteSeed

Create a new instance of the DSA Key. This is done by generating the DSA key using the arguments provided. The argument bitsOrBitsAndGenerator can be:

1.	An <Association> with the key <Integer> length in BITS and a value <ByteArray> the seed WHICH MUST BE 20 BYTES TO BE VALID.

2.	An <Integer> to just define the bits...this is shorthand for a nil exponent described above.

Arguments:

bitsOrBitsAnd20ByteSeed- <Association> described above

Answers:

< OSSslDSAKey> - DSA key

 

Instance methods: Conversion

asPublicKey

Answer a new managed instance of just the DSA public key

Answers:

< OSSslDSAKey> DSA public key

 

Instance methods: Testing

isPrivateKey

Answer true if this is a private key

Answers:

<Boolean>

 

isPublicKey

Answer true if this HAS a public key

Answers:

< Boolean>

 

supportsDigitalSignatures

Digital Signatures are supported by DSA.

Answers:

<Boolean> - true

 

supportsKeyTransport

DSA does not support key transport.

Answers:

< Boolean> - false

 

supportsProbabilisticSignatureScheme

DSA does not support PSS

Answers:

< Boolean> - false

 

OSSslECKey

Implements Elliptic Curve based cryptography algorithms

Class methods: Creation

createNew: aCurveOrGroup

Create a new instance of the EC Key Pair. The argument aCurveOrGroup can be:

1. An <OSSslECGroup> - EC Group Object

2. An <OSSslECBuiltinCurve> - EC Curve Object

Arguments:

aCurveOrGroup - described above

Answers:

< OSSslECKey> - EC key pair

 

Instance methods: Accessing

a

Answer the 'a' coefficient component of the elliptic curve.

Answers:

< OSSslBigNumber>

 

b

Answer the b coefficient component of the elliptic curve.

Answers:

< OSSslBigNumber>

 

group

Answers the EC_GROUP associated with this EC_KEY.

Answers:

< OSSslECGroup>

 

method

Answers the EC_METHOD implementation associated with the group of this PKey.

Answers:

< OSSslECMethod> - method associated with the group of this key

 

p

Answer the p prime component of the elliptic curve.

Answers:

< OSSslBigNumber>

 

publicValue

Answer the Public Value of the EC_KEY, which is an EC_POINT.

Answers:

< OSSslECPoint> - public value

 

 

 

Instance methods: API - Key Agreement

computeKey: publicValue

Computes and answers the shared secret from the private ECDH value and the other party's public value and stores it in shared secret.

Arguments:

publicValue - <OSSslECPoint>

Answers:

<ByteArray> shared secret

 

Instance methods: Conversion

asPublicKey

Answer the Public Key of the EC_KEY as an PKEY.

Answers:

< OSSslECKey> public key

 

Instance methods: Testing

isPrivateKey

Answer true if the pkey has a private key.

Answers:

<Boolean>

 

isPublicKey

Answer true if the key Is a public key.

Answers:

< Boolean>

 

supportsDigitalSignatures

Digital Signatures are supported by Elliptic Curve

Answers:

<Boolean> - true

 

supportsKeyTransport

EC does not support key transport in OpenSSL

Answers:

< Boolean> - false

 

supportsProbabilisticSignatureScheme

EC does not support PSS

Answers:

< Boolean> - false

 

Instance methods: Validation

check

Validates private EC Keys. It performs various sanity checks on the EC_KEY object to confirm that it is valid.

Answers:

<Boolean> true if validation passes, false otherwise

 

OSSslRSAKey

Implements the RSA algorithm. It can be used for secure symmetric key exchange as well as for digital signatures.

Class methods: Creation

createNew: bitsOrBitsAndExponent

Create a new instance of the RSA Key Pair. This is done by generating the RSA key using the arguments provided. The argument bitsOrBitsAndExponent can be:

1. An <Association> with the key <Integer> length in BITS and a value <Integer> the public exponent. If the exonent is nil, then the constant value OpenSSLCryptoConstants::RSA_F4 (6537) will be used.

2. An <Integer> to just define the bits...this is shorthand for a nil exponent described above. Arguments: bitsOrBitsAndExponent - <Association> described above

Answers:

< OSSslRSAKey> - RSA key

 

Instance methods: API - Digital Signatures

signPss: aByteObject with: anOSSslDigest saltLength: aLength mgf1Digest: anOSSslMgf1Digest

Answers a digital signature for @aByteObject using the

Probabilistic Signature Scheme (RSA-PSS) with MGF1 mask gen function.

Note: The RSA Pkey must have a private key

If not, an error object is answered

 

Arguments:

aByteObject - @see implementors of isOpenSSLByteObject for types

anOSSslDigest - <OSSslDigest> message digest algorithm

aLength - <Integer> in octects of the salt

 

anOSSslMgf1Digest- <OSSslDigest> hash algorithm used in MGF1

 

Answers:

<ByteArray> digital signature of @aByteObject

 

verifyPss: signature from: aByteObject with: anOSSslDigest with: aLength saltLength: aLength mgf1Digest: anOSSslMgf1Digest

Answers a <Boolean> indicating if the digital signature for @aByteObject using the Probabilistic Signature Scheme (RSA-PSS) with MGF1 mask gen function is verified

Note: The RSA Pkey must have a private key. If not, an error object is answered.

Arguments:

Signature - @see implementors of isOpenSSLByteObject for types

aByteObject - a collection of bytes THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)

anOSSslDigest - <OSSslDigest> message digest algorithm

aLength - <Integer> in octects of the salt

anOSSslMgf1Digest - <OSSslDigest> hash algorithm used in MGF1

Answers:

<Boolean> true if the digital signature is verified

 

 

Instance methods: Conversion

asPublicKey

Answer a new managed instance of just the public key from this key pair.

Answers:

< OSSslRSAKey > RSA public key

 

Instance methods: Testing

isPrivateKey

Answer true if this is a private key

Answers:

<Boolean>

 

isPublicKey

RSA always has a public key.

Answers:

< True>

 

supportsDigitalSignatures

RSA supports digital signatures.

Answers:

<Boolean> - true

 

supportsKeyTransport

RSA supports key transport.

Answers:

< Boolean> - true

 

supportsProbabilisticSignatureScheme

RSA supports PSS (RSA-PSS) in OpenSSL

Answers:

< Boolean> - true

 

Instance methods: Validation

check

Validates private RSA Keys.

It does not work on RSA public keys that have only the modulus and public exponent elements populated. Checks that p and q are in fact prime, and that n = p*q. Checks that d*e = 1 mod (p-1*q-1), and that dmp1, dmq1 and iqmp are set correctly or are NULL. Performs integrity checks on all the RSA key material, so the RSA key structure must contain all the private key data too. Therefore, it cannot be used with any arbitrary RSA key object, even if it is otherwise fit for regular RSA operation.

Answers:

<Boolean> true if public key or validated private key.

OpenSSLEnvelope

Object representation of a digital envelope.

Instance methods: Accessing

data

Depending on the context (seal or open), this answers the (encrypted or decrypted) data.

Answers:

<ByteArray | String | OSStringZ> - byte collection that knows its size

 

data: aByteObject

Depending on the context (seal or open), this sets the (encrypted or decrypted) data.

Answers:

aByteObject - <ByteArray | String | OSStringZ> - byte collection that knows its size

 

iv

Answer the initialization vector <ByteArray>.

Answers:

< ByteArray >

 

iv: aByteArray

Sets the initialization vector <ByteArray>.

Arguments:

aByteArray - <ByteArray> initialization vector

 

sessionKey

Answer the encrypted session key which was encrypted using a public key. The owning of the associated private key is the only one that can decrypt the session key.

Answers:

<ByteArray>

 

sessionKey: anEncryptedByteArray

Sets the encrypted session key which was encrypted using a public key. The owning of the associated private key is the only one that can decrypt the session key.

Arguments:

anEncryptedByteArray - <ByteArray>

 

Instance methods: API

discard

After opening an envelope, the caller should try and remember to discard it which cleanses the memory. If not, the GC will take care of it but its a good policy to leave sensitive information in memory only as long as needed. It is expected that the envelopes of multiple clients are not in the same memory space. When creating n number of envelopes, the encrypted data and iv point to the same object. The session key is unique per envelope. Therefore, you should not call it under these conditions because doing so will cleanse the data for all envelopes in the image.

Extensions

OSSslCipher

open: anEnvelope with: anOSSslPKey

Open anEnvelope <OpenSSLEnvelope> using the private key anOSSslPKey that was associated with the envelope when it was sealed.

Arguments:

anEnvelope - <OpenSSLEnvelope> sealed envelope

anOSSslPKey - <OSSslPKey> private key

Answers:

<ByteArray> - decrypted contents

 

seal: aByteObject withAll: aCollectionOfOSSslPKeys

Create envelopes (1 for each public key in aCollectionOfOSSslPKeys) and seal the envelopes <OpenSSLEnvelope> using the public keys.

Arguments:

aByteObject - a collection of bytes to encrypt THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)

aCollectionOfOSSslPKeys - <SequenceableCollection of <OSSslPKey>> public keys

Answers:

<Array of <OpenSSLEnvelope>> - collection of envelopes associated with the public keys in the same order defined in aCollectionOfOSSslPKeys

OSSslCipherCtx

 

open: anEnvelope with: anOSSslPKey

Open anEnvelope <OpenSSLEnvelope> using the private key anOSSslPKey that was associated with the envelope when it was sealed.

Arguments:

anEnvelope - <OpenSSLEnvelope> sealed envelope

anOSSslPKey - <OSSslPKey> private key

Answers:

<ByteArray> - decrypted contents

 

seal: aByteObject withAll: aCollectionOfOSSslPKeys

Create envelopes (1 for each public key in aCollectionOfOSSslPKeys) and seal the envelopes <OpenSSLEnvelope> using the public keys.

Arguments:

aByteObject - a collection of bytes to encrypt THAT MUST KNOW ITS SIZE (i.e. String | ByteArray | OSStringZ)

aCollectionOfOSSslPKeys - <SequenceableCollection of <OSSslPKey>> public keys

Answers:

<Array of <OpenSSLEnvelope>> - collection of envelopes associated with the public keys in the same order defined in aCollectionOfOSSslPKeys