/**

* A language-independent library for reasoning about cryptography.

*/

overlay[local?]

module;

import codeql.util.Location

signature module InputSig<LocationSig Location> {

class LocatableElement {

Location getLocation();

string toString();

}

class DataFlowNode {

Location getLocation();

string toString();

}

class UnknownLocation instanceof Location;

string locationToFileBaseNameAndLineNumberString(Location location);

LocatableElement dfn_to_element(DataFlowNode node);

predicate artifactOutputFlowsToGenericInput(

DataFlowNode artifactOutput, DataFlowNode otherFlowAwareInput

);

}

module CryptographyBase<LocationSig Location, InputSig<Location> Input> {

import Standardization::Types

final class LocatableElement = Input::LocatableElement;

final class UnknownLocation = Input::UnknownLocation;

final class DataFlowNode = Input::DataFlowNode;

/**

* A `ConsumerInputDataFlowNode` is a `DataFlowNode` that represents a consumer of data.

*

* This class is equivalent to `DataFlowNode` but facilitates binding to a `ConsumerElement`.

*/

class ConsumerInputDataFlowNode extends DataFlowNode {

ConsumerElement getConsumer() { result.getInputNode() = this }

}

/**

* An `ArtifactOutputDataFlowNode` is a `DataFlowNode` that represents the source of a created artifact.

*

* This class is equivalent to `DataFlowNode` but facilitates binding to an `OutputArtifactInstance`.

*/

class ArtifactOutputDataFlowNode extends DataFlowNode {

OutputArtifactInstance getArtifact() { result.getOutputNode() = this }

}

final class UnknownPropertyValue extends string {

UnknownPropertyValue() { this = "<unknown>" }

}

bindingset[root]

private string getPropertyAsGraphString(NodeBase node, string key, Location root) {

result =

strictconcat(string value, Location location, string parsed |

node.properties(key, value, location) and

(

if location = root or location instanceof UnknownLocation

then parsed = value

else

parsed =

"(" + value + "," + Input::locationToFileBaseNameAndLineNumberString(location) + ")"

)

|

parsed, ","

)

}

bindingset[node]

predicate node_as_property(GenericSourceNode node, string value, Location location) {

value =

node.getInternalType() + ":" +

node.asElement().(GenericSourceInstance).getAdditionalDescription() and

location = node.getLocation()

}

NodeBase getPassthroughNodeChild(NodeBase node) { result = node.getChild(_) }

predicate isPassthroughNodeWithSource(NodeBase node) {

isPassthroughNode(node) and

exists(node.asElement().(ArtifactConsumerAndInstance).getASource())

}

predicate isPassthroughNode(NodeBase node) {

node.asElement() instanceof ArtifactConsumerAndInstance

}

predicate nodes_graph_impl(NodeBase node, string key, string value) {

not node.isExcludedFromGraph() and

not isPassthroughNodeWithSource(node) and // TODO: punt to fix known unknowns for passthrough nodes

(

key = "semmle.label" and

value = node.toString()

or

// CodeQL's DGML output does not include a location

key = "Location" and

value = Input::locationToFileBaseNameAndLineNumberString(node.getLocation()) // node.getLocation().toString()

or

// Known unknown edges should be reported as properties rather than edges

node = node.getChild(key) and

value = "<unknown>"

or

// Report properties

value = getPropertyAsGraphString(node, key, node.getLocation())

)

}

predicate edges_graph_impl(NodeBase source, NodeBase target, string key, string value) {

key = "semmle.label" and

exists(NodeBase directTarget |

directTarget = source.getChild(value) and

// [NodeA] ---Input--> [Passthrough] ---Source---> [NodeB]

// should get reported as [NodeA] ---Input--> [NodeB]

if isPassthroughNode(directTarget)

then target = getPassthroughNodeChild(directTarget)

else target = directTarget

) and

// Known unknowns are reported as properties rather than edges

not source = target

}

/**

* An element that is flow-aware, i.e., it has an input and output node implicitly used for data flow analysis.

*/

abstract private class FlowAwareElementImpl extends LocatableElement {

/**

* Gets the output node for this element, which should usually be the same as `this`.

*/

abstract DataFlowNode getOutputNode();

/**

* Gets the input node for this element which takes in data.

*

* If `getInput` is implemented as `none()`, the artifact will not have inbound flow analysis.

*/

abstract ConsumerInputDataFlowNode getInputNode();

/**

* Holds if this element flows to `other`.

*

* This predicate should be defined generically per-language with library-specific extension support.

* The expected implementation is to perform flow analysis from this element's output to another element's input.

* The `other` argument should be one or more `FlowAwareElement`s that are sinks of the flow.

*

* If `flowsTo` is implemented as `none()`, the artifact will not have outbound flow analysis.

*/

abstract predicate flowsTo(FlowAwareElement other);

}

final class FlowAwareElement = FlowAwareElementImpl;

/**

* An element that represents a _known_ cryptographic asset with a determinable value OR an artifact.

*

* CROSS PRODUCT WARNING: Modeling any *other* element that is a `FlowAwareElement` to the same

* instance in the database will result in every `FlowAwareElement` sharing the output flow.

*/

abstract private class KnownElement extends LocatableElement {

final ConsumerElement getAConsumer() { result.getAKnownSource() = this }

}

/**

* An element that represents a _known_ cryptographic operation.

*/

abstract class OperationInstance extends KnownElement {

/**

* Gets the consumers of algorithm values associated with this operation.

*/

abstract AlgorithmValueConsumer getAnAlgorithmValueConsumer();

}

/**

* An element that represents a _known_ cryptographic algorithm.

*/

abstract class AlgorithmInstance extends KnownElement { }

/**

* An element that represents a generic source of data.

*

* A generic source of data is either:

* 1. A value (e.g., a string or integer literal) *or*

* 1. An input for which a value cannot be determined (e.g., `argv`, file system reads, and web request headers)

*/

abstract class GenericSourceInstance extends FlowAwareElementImpl {

final override ConsumerInputDataFlowNode getInputNode() { none() }

abstract string getInternalType();

string getAdditionalDescription() { none() }

}

/**

* An element that has a constant value and is a generic source of data.

*/

abstract class GenericValueSourceInstance extends GenericSourceInstance { }

/**

* An element with a constant value, such as a literal.

*/

abstract class GenericConstantSourceInstance extends GenericValueSourceInstance {

final override string getInternalType() { result = "Constant" }

}

/**

* An element representing statically or dynamically allocated data.

*/

abstract class GenericAllocationSourceInstance extends GenericValueSourceInstance {

final override string getInternalType() { result = "Allocation" }

}

/**

* An element that does not have a determinable constant value and is a generic source of data.

*/

abstract class GenericNoValueSourceInstance extends GenericSourceInstance { }

/**

* A call to or an output argument of an external function with no definition.

*/

abstract class GenericExternalCallSource extends GenericNoValueSourceInstance {

final override string getInternalType() { result = "ExternalCall" } // TODO: call target name or toString of source?

}

/**

* A parameter of a function which has no identifiable callsite.

*/

abstract class GenericUnreferencedParameterSource extends GenericNoValueSourceInstance {

final override string getInternalType() { result = "Parameter" } // TODO: toString of source?

}

/**

* A source of remote or external data, such as web request headers.

*/

abstract class GenericRemoteDataSource extends GenericNoValueSourceInstance {

// TODO: avoid duplication with the above types?.. perhaps define the above generically then override

final override string getInternalType() { result = "RemoteData" } // TODO: toString of source?

}

/**

* A source of local or environment data, such as environment variables or a local filesystem.

*/

abstract class GenericLocalDataSource extends GenericNoValueSourceInstance {

// TODO: avoid duplication with the above types

final override string getInternalType() { result = "LocalData" } // TODO: toString of source?

}

/**

* An element that consumes _known_ or _unknown_ cryptographic assets.

*

* Note that known assets are to be modeled explicitly with the `getAKnownSource` predicate, whereas

* unknown assets are modeled implicitly via flow analysis from any `GenericSourceInstance` to this element.

*

* A consumer can consume multiple instances and types of assets at once, e.g., both a `PaddingAlgorithm` and `CipherAlgorithm`.

*/

abstract private class ConsumerElement extends FlowAwareElementImpl {

abstract KnownElement getAKnownSource();

override predicate flowsTo(FlowAwareElement other) { none() }

override DataFlowNode getOutputNode() { none() }

final GenericSourceInstance getAGenericSource() {

result.flowsTo(this) and not result = this.getAKnownSource()

}

final GenericSourceNode getAGenericSourceNode() {

result.asElement() = this.getAGenericSource()

}

final NodeBase getAKnownSourceNode() { result.asElement() = this.getAKnownSource() }

final LocatableElement getASource() {

result = this.getAGenericSource() or

result = this.getAKnownSource()

}

}

/**

* A generic value consumer, e.g. for inputs such as key length.

* TODO: type hints or per-instantiation type hint config on the source/sink pairs.

*/

final private class GenericValueConsumer extends ConsumerElement {

ConsumerInputDataFlowNode input;

GenericValueConsumer() {

(

exists(KeyCreationOperationInstance op | input = op.getKeySizeConsumer())

or

exists(KeyGenerationOperationInstance op | input = op.getKeyValueConsumer())

or

exists(KeyDerivationOperationInstance op |

input = op.getIterationCountConsumer() or

input = op.getOutputKeySizeConsumer()

)

) and

this = Input::dfn_to_element(input)

}

final override KnownElement getAKnownSource() { none() }

final override ConsumerInputDataFlowNode getInputNode() { result = input }

}

/**

* An `AlgorithmValueConsumer` (_AVC_) is an element that consumes a value specifying an algorithm.

*

* Example 1:

* `arg0` of `set_algorithm` (`x`) is the AVC for the `ctx.encrypt()` operation.

* ```cpp

* x = "RSA";

* ctx.set_algorithm(x);

* ctx.encrypt();

* ```

*

* Example 2:

* `encrypt_with_rsa` is concurrently an an operation, an AVC, and an algorithm.

* ```cpp

* `encrypt_with_rsa();`

* ```

*/

abstract class AlgorithmValueConsumer extends ConsumerElement {

/**

* DO NOT USE.

* Model `getAKnownAlgorithmSource()` instead, which is equivalent but correctly typed.

*/

final override KnownElement getAKnownSource() { result = this.getAKnownAlgorithmSource() }

/**

* Gets a known algorithm value that is equivalent to or consumed by this element.

*/

abstract AlgorithmInstance getAKnownAlgorithmSource();

}

/**

* An element that represents a _known_ cryptographic artifact.

*/

abstract class ArtifactInstance extends KnownElement, FlowAwareElementImpl {

abstract predicate isConsumerArtifact(); // whether this is an input artifact defined by its consumer

}

/**

* An `ArtifactConsumer` represents an element in code that consumes an artifact.

*

* The concept of "`ArtifactConsumer` = `ArtifactNode`" should be used for inputs, as a consumer can be directly tied

* to the artifact it receives, thereby becoming the definitive contextual source for that artifact.

*

* Architectural Implications:

* * By directly coupling a consumer with the node that receives an artifact, no modeling considerations have to be made

* to provide an interface for identifying the source via the consumer data-flow mechanisms.

* * An artifact's properties (such as being a nonce) are not necessarily inherent; they are determined by the context in which the artifact is consumed.

* The consumer node is therefore essential in defining these properties for inputs.

* * This approach reduces ambiguity by avoiding separate notions of "artifact source" and "consumer", as the node itself encapsulates both roles.

* * Instances of nodes do not necessarily have to come from a consumer, allowing additional modeling of an artifact to occur outside of the consumer.

*/

abstract class ArtifactConsumer extends ConsumerElement {

/**

* Use `getAKnownArtifactSource() instead. The behavior of these two predicates is equivalent.

*/

final override KnownElement getAKnownSource() { result = this.getAKnownArtifactSource() }

final ArtifactInstance getAKnownArtifactSource() { result.flowsTo(this) }

}

/**

* An `ArtifactConsumer` that is also an `ArtifactInstance`.

*

* For example:

* A `NonceArtifactConsumer` is always the `NonceArtifactInstance` itself, since data only becomes (i.e., is determined to be)

* a `NonceArtifactInstance` when it is consumed in a context that expects a nonce (e.g., an argument expecting nonce data).

*

* In this case, the artifact (nonce) is fully defined by the context in which it is consumed, and the consumer embodies

* that identity without the need for additional differentiation. Without the context a consumer provides, that data could

* otherwise be any other type of artifact or even simply random data.

*

* This class is used to create synthetic nodes for the artifact at any place where it is consumed.

*/

abstract private class ArtifactConsumerAndInstance extends ArtifactConsumer, ArtifactInstance {

final override predicate isConsumerArtifact() { any() }

}

final private class NonceArtifactConsumer extends ArtifactConsumerAndInstance {

ConsumerInputDataFlowNode inputNode;

NonceArtifactConsumer() {

exists(KeyOperationInstance op | inputNode = op.getNonceConsumer()) and

this = Input::dfn_to_element(inputNode)

}

final override ConsumerInputDataFlowNode getInputNode() { result = inputNode }

}

final private class MessageArtifactConsumer extends ArtifactConsumerAndInstance {

ConsumerInputDataFlowNode inputNode;

MessageArtifactConsumer() {

(

exists(KeyOperationInstance op | inputNode = op.getInputConsumer())

or

exists(KeyDerivationOperationInstance op | inputNode = op.getInputConsumer())

or

exists(HashOperationInstance op | inputNode = op.getInputConsumer())

) and

this = Input::dfn_to_element(inputNode)

}

final override ConsumerInputDataFlowNode getInputNode() { result = inputNode }

}

final private class SaltArtifactConsumer extends ArtifactConsumerAndInstance {

ConsumerInputDataFlowNode inputNode;

SaltArtifactConsumer() {

exists(KeyDerivationOperationInstance op | inputNode = op.getSaltConsumer()) and

this = Input::dfn_to_element(inputNode)

}

final override ConsumerInputDataFlowNode getInputNode() { result = inputNode }

}

final private class SignatureArtifactConsumer extends ArtifactConsumerAndInstance {

ConsumerInputDataFlowNode inputNode;

SignatureArtifactConsumer() {

exists(SignatureOperationInstance op | inputNode = op.getSignatureConsumer()) and

this = Input::dfn_to_element(inputNode)

}

final override ConsumerInputDataFlowNode getInputNode() { result = inputNode }

}

/**

* An artifact that is produced by an operation, representing a concrete artifact instance rather than a synthetic consumer artifact.

*/

abstract class OutputArtifactInstance extends ArtifactInstance {

override predicate isConsumerArtifact() { none() }

override ConsumerInputDataFlowNode getInputNode() { none() }

final override predicate flowsTo(FlowAwareElement other) {

Input::artifactOutputFlowsToGenericInput(this.getOutputNode(), other.getInputNode())

}

}

/**

* An artifact representing a random number generator's output.

*/

abstract class RandomNumberGenerationInstance extends OutputArtifactInstance {

abstract string getGeneratorName();

}

/**

* An artifact representing a key operation's output, e.g.:

* 1. Encryption/decryption output (ciphertext or plaintext)

* 1. Signing output (signature)

* 1. Key encapsulation output (wrapped or unwrapped key)

*/

final class KeyOperationOutputArtifactInstance extends OutputArtifactInstance {

KeyOperationInstance creator;

KeyOperationOutputArtifactInstance() {

Input::dfn_to_element(creator.getOutputArtifact()) = this

}

override DataFlowNode getOutputNode() { result = creator.getOutputArtifact() }

KeyOperationInstance getCreator() { result = creator }

}

/**

* An artifact representing the message digest output of a hash operation.

*/

final class HashOutputArtifactInstance extends OutputArtifactInstance {

HashOperationInstance creator;

HashOutputArtifactInstance() { Input::dfn_to_element(creator.getOutputArtifact()) = this }

override DataFlowNode getOutputNode() { result = creator.getOutputArtifact() }

}

/**

* An artifact representing the shared secret generated by key agreement operations.

*/

final class KeyAgreementSharedSecretOutputArtifactInstance extends OutputArtifactInstance {

KeyAgreementSecretGenerationOperationInstance creator;

KeyAgreementSharedSecretOutputArtifactInstance() {

Input::dfn_to_element(creator.getOutputArtifact()) = this

}

override DataFlowNode getOutputNode() { result = creator.getOutputArtifact() }

}

// Artifacts that may be outputs or inputs

newtype TKeyArtifactType =

TSymmetricKeyType() or

TAsymmetricKeyType() or

TUnknownKeyType()

class KeyArtifactType extends TKeyArtifactType {

string toString() {

this = TSymmetricKeyType() and result = "Symmetric"

or

this = TAsymmetricKeyType() and result = "Asymmetric"

or

this = TUnknownKeyType() and result = "Unknown"

}

}

abstract private class KeyArtifactInstance extends ArtifactInstance {

abstract KeyArtifactType getKeyType();

}

final class KeyArtifactOutputInstance extends KeyArtifactInstance, OutputArtifactInstance {

KeyCreationOperationInstance creator;

KeyArtifactOutputInstance() { Input::dfn_to_element(creator.getOutputKeyArtifact()) = this }

final KeyCreationOperationInstance getCreator() { result = creator }

override KeyArtifactType getKeyType() { result = creator.getOutputKeyType() }

override DataFlowNode getOutputNode() { result = creator.getOutputKeyArtifact() }

}

final class KeyArtifactConsumer extends KeyArtifactInstance, ArtifactConsumerAndInstance {

ConsumerInputDataFlowNode inputNode;

// TODO: key type hint? e.g. hint: private || public

KeyArtifactConsumer() {

(

exists(KeyOperationInstance op | inputNode = op.getKeyConsumer())

or

exists(KeyGenerationOperationInstance op | inputNode = op.getKeyValueConsumer())

or

exists(KeyAgreementSecretGenerationOperationInstance op |

inputNode = op.getServerKeyConsumer() or

inputNode = op.getPeerKeyConsumer()

)

) and

this = Input::dfn_to_element(inputNode)

}

override KeyArtifactType getKeyType() { result instanceof TUnknownKeyType } // A consumer node does not have a key type, refer to source (TODO: refine, should this be none())

final override ConsumerInputDataFlowNode getInputNode() { result = inputNode }

}

/**

* A key-based cryptographic operation instance, encompassing:

* - **Ciphers**: Encryption and decryption, both symmetric and asymmetric

* - **Signing**: Signing and verifying

* - **MACs**: Mac generation

* - **Key encapsulation**: Key wrapping and unwrapping

*

* This class represents a generic key operation that transforms input data

* using a cryptographic key, producing an output artifact such as ciphertext,

* plaintext, a signature, or an (un-)wrapped key.

*/

abstract class KeyOperationInstance extends OperationInstance {

final KeyOperationOutputArtifactInstance getOutputArtifactInstance() {

result.getOutputNode() = this.getOutputArtifact()

}

/**

* Gets the subtype of this key operation, distinguishing operations such as

* encryption, decryption, signing, verification, key wrapping, and key unwrapping.

*/

abstract KeyOperationSubtype getKeyOperationSubtype();

/**

* Gets the consumer of the cryptographic key used in this key operation.

* The key may be symmetric or asymmetric, depending on the operation subtype.

*/

abstract ConsumerInputDataFlowNode getKeyConsumer();

/**

* Gets the consumer of nonces or initialization vectors (IVs) associated with this key operation.

* These are typically required for encryption, AEAD, or wrap modes.

*

* If the operation does not require a nonce, this predicate should be implemented as `none()`.

*/

abstract ConsumerInputDataFlowNode getNonceConsumer();

/**

* Gets the consumer of the primary message input for this key operation.

* For example: plaintext (for encryption), ciphertext (for decryption),

* a message to be signed or verified, the message on which a mac is generated,

* or a wrapped key to be unwrapped.

*/

abstract ConsumerInputDataFlowNode getInputConsumer();

/**

* Gets the output artifact produced by this key operation.

* This may represent ciphertext, a digital signature, a wrapped key, or any

* other data resulting from the operation.

*

* Implementation guidelines:

* 1. Each semantically meaningful output should result in an artifact.

* 2. Discarded or transient intermediate values should not be artifacts.

*/

abstract ArtifactOutputDataFlowNode getOutputArtifact();

}

/**

* A key-based algorithm instance used in cryptographic operations such as encryption, decryption,

* signing, verification, and key wrapping.

*/

abstract class KeyOperationAlgorithmInstance extends AlgorithmInstance {

/**

* Gets the raw algorithm name as provided in source, e.g., "AES/CBC/PKCS7Padding".

* This name is not parsed or normalized.

*/

abstract string getRawAlgorithmName();

/**

* Gets the key operation algorithm type, e.g., `TSignature(Ed25519())` or `TSymmetricCipher(AES())`.

*

* If the category of algorithm is known, but the precise algorithm is not, the following type hints should be used:

* - `TSymmetricCipher(OtherSymmetricCipherType())`

* - `TAsymmetricCipher(OtherAsymmetricCipherType())`

* - `TSignature(OtherSignatureAlgorithmType())`

* - `TMacAlgorithm(OtherMacAlgorithmType())`

* - `TKeyEncapsulation(OtherKEMAlgorithmType())`

*

* If the category of algorithm is not known, the following type should be used:

* - `TUnknownKeyOperationAlgorithmType()`

*

* This predicate should always hold.

*/

abstract KeyOpAlg::AlgorithmType getAlgorithmType();

/**

* Gets the mode of operation, such as "CBC", "GCM", or "ECB".

*

* Edge-cases and modeling guidance:

* - Mode of operation not identifiable: result is `none()`.

* - No mode possible (e.g., RSA, DSA, or ChaCha20): result is `none()`.

* - Mode of operation explicitly specified as none: result is `ModeOfOperationAlgorithmInstance`.

*

* IMPLEMENTATION NOTE: This is treated as part of the algorithm identity and

* not modeled as a separate algorithm value consumer.

*/

abstract ModeOfOperationAlgorithmInstance getModeOfOperationAlgorithm();

/**

* Gets the padding scheme, such as "PKCS7", "OAEP", or "NoPadding".

*

* See the modeling guidance for `getModeOfOperationAlgorithm` for modeling guidance.

*/

abstract PaddingAlgorithmInstance getPaddingAlgorithm();

/**

* Gets the key size in bits specified for this algorithm variant, for example, "128" for "AES-128". This predicate is only

* necessary to specify if there are multiple variants of the algorithm defined by key size and a specific key size is known.

*

* If a specific key size is unknown, this predicate should be implemented as `none()`.

*

* If the algorithm accepts a range of key sizes without a particular one specified, this predicate should be implemented as `none()`.

*

* NOTE: if the algorithm has a single key size, the implicit key size does not need to be modeled.

* This will be automatically inferred and applied at the node level.

* See `fixedImplicitCipherKeySize`.

*/

abstract int getKeySizeFixed();

/**

* Gets a consumer for the key size in bits specified for this algorithm variant.

*/

abstract ConsumerInputDataFlowNode getKeySizeConsumer();

/**

* Holds if this algorithm is expected to have a mode specified.

*/

predicate shouldHaveModeOfOperation() { any() }

/**

* Holds if this algorithm is expected to have a padding scheme specified.

*/

predicate shouldHavePaddingScheme() { any() }

}

abstract class HmacAlgorithmInstance extends KeyOperationAlgorithmInstance {

HmacAlgorithmInstance() { this.getAlgorithmType() = KeyOpAlg::TMac(KeyOpAlg::HMAC()) }

/**

* Gets the hash algorithm used by this HMAC algorithm.

*/

abstract AlgorithmValueConsumer getHashAlgorithmValueConsumer();

/**

* CMACs will have algorithms that have modes of operation but that

* is associated with the cipher algorithm, that is itself

* associated to the MAC algorithm.

*/

override predicate shouldHaveModeOfOperation() { none() }

override ModeOfOperationAlgorithmInstance getModeOfOperationAlgorithm() { none() }

/**

* CMACs may have padding but the padding is associated with the cipher algorithm,

* that is itself associated to the MAC algorithm.

*/

override predicate shouldHavePaddingScheme() { none() }

override PaddingAlgorithmInstance getPaddingAlgorithm() { none() }

}

abstract class CmacAlgorithmInstance extends KeyOperationAlgorithmInstance {

CmacAlgorithmInstance() { this.getAlgorithmType() = KeyOpAlg::TMac(KeyOpAlg::CMAC()) }

/**

* Gets the cipher algorithm used by this CMAC algorithm.

*/

abstract AlgorithmValueConsumer getCipherAlgorithmValueConsumer();

}

abstract class ModeOfOperationAlgorithmInstance extends AlgorithmInstance {

/**

* Gets the type of this mode of operation, e.g., "ECB" or "CBC".

*

* When modeling a new mode of operation, use this predicate to specify the type of the mode.

*

* If a type cannot be determined, the result is `OtherMode`.

*/

abstract KeyOpAlg::ModeOfOperationType getModeType();

/**

* Gets the isolated name as it appears in source, e.g., "CBC" in "AES/CBC/PKCS7Padding".

*

* This name should not be parsed or formatted beyond isolating the raw mode name if necessary.

*/

abstract string getRawModeAlgorithmName();

}

abstract class PaddingAlgorithmInstance extends AlgorithmInstance {

/**

* Gets the isolated name as it appears in source, e.g., "PKCS7Padding" in "AES/CBC/PKCS7Padding".

*

* This name should not be parsed or formatted beyond isolating the raw padding name if necessary.

*/

abstract string getRawPaddingAlgorithmName();

/**

* Gets the type of this padding algorithm, e.g., "PKCS7" or "OAEP".

*

* When modeling a new padding algorithm, use this predicate to specify the type of the padding.

*

* If a type cannot be determined, the result is `OtherPadding`.

*/

abstract KeyOpAlg::PaddingSchemeType getPaddingType();

}

abstract class OaepPaddingAlgorithmInstance extends PaddingAlgorithmInstance {

OaepPaddingAlgorithmInstance() { this.getPaddingType() instanceof KeyOpAlg::OAEP }

/**

* Gets the hash algorithm used in this padding scheme.

*/

abstract HashAlgorithmInstance getOaepEncodingHashAlgorithm();

/**

* Gets the hash algorithm used by MGF1 (assumption: MGF1 is the only MGF used by OAEP)

*/

abstract HashAlgorithmInstance getMgf1HashAlgorithm();

}

/**

* A parent class for signature and MAC operations.

* Signatures and macs are the asymmetric and symmetric analogs of each other,

* and some APIs can reuse a single operation to do either signing on mac.

* Users should extend this class when an operation can be either a signature or a MAC,

* and where the instance is not obviously one or the other from use.

*/

abstract class SignatureOrMacOperationInstance extends KeyOperationInstance {

/**

* Gets the consumer of a hash algorithm.

* This is intended for mac/signing operations they are explicitly configured

* with a hash algorithm. If the operation is not configured with an explicit

* hash algorithm, users do not need to provide a consumer (set none()).

*/

abstract AlgorithmValueConsumer getHashAlgorithmValueConsumer();

/**

* Holds if this operation has a hash algorithm consumer.

* I.e., holds if the operation is configured to perform a hash

* on a message before signing and algorithm is passed in.

* The hash algorithm consumer must be specified through

* `getHashAlgorithmValueConsumer()`.

*/

abstract predicate hasHashAlgorithmConsumer();

}

/**

* A key operation instance representing a signature being generated or verified.

* Note: These instances are known to always be signature operations.

* If an API allows an operation to be used for both MAC and signature,

* it should be modeled as a `SignatureOrMacOperationInstance` instead,

* even if all configuration paths to the current operation only configure it as a signature operation.

*/

abstract class SignatureOperationInstance extends SignatureOrMacOperationInstance {

/**

* Gets the consumer of the signature when this operation is a verification operation.

*/

abstract ConsumerInputDataFlowNode getSignatureConsumer();

}

abstract class MacOperationInstance extends SignatureOrMacOperationInstance { }

abstract class EllipticCurveInstance extends AlgorithmInstance {

/**

* Gets the isolated name as it appears in source

*

* This name should not be parsed or formatted beyond isolating the raw name if necessary.

*/

abstract string getRawEllipticCurveName();

abstract TEllipticCurveType getEllipticCurveType();

abstract int getKeySize();

/**

* The 'parsed' curve name, e.g., "P-256" or "secp256r1"

* The parsed name is full name of the curve, including the type, key size, and other

* typical parameters found on the name.

*

* In many cases this will be equivalent to `getRawEllipticCurveAlgorithmName()`,

* but not always (e.g., if the curve is specified through a raw NID).

*

* In cases like an NID, we want the standardized name so users can quickly

* understand what the curve is, while also parsing out the type and key size

* separately.

*/

string getParsedEllipticCurveName() { result = this.getRawEllipticCurveName() }

}

abstract class HashOperationInstance extends OperationInstance {

abstract ArtifactOutputDataFlowNode getOutputArtifact();

abstract ConsumerInputDataFlowNode getInputConsumer();

}

abstract class HashAlgorithmInstance extends AlgorithmInstance {

/**

* Gets the type of this digest algorithm, e.g., "SHA1", "SHA2", "MD5" etc.

*/

abstract THashType getHashType();

/**

* Gets the isolated name as it appears in source, e.g., "SHA-256" in "SHA-256/PKCS7Padding".

*/

abstract string getRawHashAlgorithmName();

/**

* Gets the length of the hash digest in bits if it is not an implicit size

* and is not fixed by the algorithm.

* For example, SHA-256 has a fixed length of 256 bits.

* SHA-1 should not be modled with digest length as it is always 160 bits.

* Fixed length digests are modeled with `fixedImplicitDigestLength` and

* are used at the node level.

*/

abstract int getFixedDigestLength();

}

predicate fixedImplicitDigestLength(THashType type, int digestLength) {

type instanceof SHA1 and digestLength = 160

or

type instanceof MD5 and

digestLength = 128

or

type instanceof RIPEMD160 and

digestLength = 160

or

type instanceof WHIRLPOOL and

digestLength = 512 // TODO: verify

}

/**

* An operation that generates, derives, or loads a cryptographic key.

*

* Library modeling should not extend this class directly but rather extend

* `KeyGenerationOperationInstance`, `KeyDerivationOperationInstance`, or `KeyLoadOperationInstance`.

*/

abstract class KeyCreationOperationInstance extends OperationInstance {

abstract string getKeyCreationTypeDescription();

/**

* Gets the key artifact produced by this operation.

*/

abstract ArtifactOutputDataFlowNode getOutputKeyArtifact();

/**

* Gets the key artifact type produced.

*/

abstract KeyArtifactType getOutputKeyType();

// Defaults or fixed values

int getKeySizeFixed() { none() }

// Consumer input nodes

abstract ConsumerInputDataFlowNode getKeySizeConsumer();

final KeyArtifactOutputInstance getKeyArtifactOutputInstance() {

result.getOutputNode() = this.getOutputKeyArtifact()

}

}

/**

* An operation that derives a key from an input password or other data.

*/

abstract class KeyDerivationOperationInstance extends KeyCreationOperationInstance {

final override KeyArtifactType getOutputKeyType() { result instanceof TSymmetricKeyType }

final override string getKeyCreationTypeDescription() { result = "KeyDerivation" }

// Defaults or fixed values

string getIterationCountFixed() { none() }

string getOutputKeySizeFixed() { none() }

// Generic consumer input nodes

abstract ConsumerInputDataFlowNode getIterationCountConsumer();

abstract ConsumerInputDataFlowNode getOutputKeySizeConsumer();

// Artifact consumer input nodes

abstract ConsumerInputDataFlowNode getInputConsumer();

abstract ConsumerInputDataFlowNode getSaltConsumer();

}

newtype TKeyDerivationType =

PBKDF2() or

PBES() or

HKDF() or

ARGON2() or

SCRYPT() or

OtherKeyDerivationType()

abstract class KeyDerivationAlgorithmInstance extends AlgorithmInstance {

/**

* Gets the type of this key derivation algorithm, e.g., "PBKDF2" or "HKDF".

*/

abstract TKeyDerivationType getKdfType();

/**

* Gets the isolated name as it appears in source, e.g., "PBKDF2WithHmacSHA256" in "PBKDF2WithHmacSHA256/UnrelatedInformation".

*/

abstract string getRawKdfAlgorithmName();

}

abstract class Pbkdf2AlgorithmInstance extends KeyDerivationAlgorithmInstance {

Pbkdf2AlgorithmInstance() { this.getKdfType() instanceof PBKDF2 }

/**

* Gets the HMAC algorithm used by this PBKDF2 algorithm.

*

* Note: Other PRFs are not supported, as most cryptographic libraries

* only support HMAC for PBKDF2's PRF input.

*/

abstract AlgorithmValueConsumer getHmacAlgorithmValueConsumer();

}

abstract class ScryptAlgorithmInstance extends KeyDerivationAlgorithmInstance {

ScryptAlgorithmInstance() { this.getKdfType() instanceof SCRYPT }

/**

* Gets the HMAC algorithm used by this PBKDF2 algorithm.

*

* Note: Other PRFs are not supported, as most cryptographic libraries

* only support HMAC for PBKDF2's PRF input.

*/

abstract AlgorithmValueConsumer getHmacAlgorithmValueConsumer();

}

abstract class KeyGenerationOperationInstance extends KeyCreationOperationInstance {

final override string getKeyCreationTypeDescription() { result = "KeyGeneration" }

/**

* Gets the consumer of a key for this key generaiton operation.

* This occurs when a key generation operaiton is based on a raw key value

* or it generates another key or key context from a previously generated key.

*/

abstract ConsumerInputDataFlowNode getKeyValueConsumer();

/**

* Holds if the key generation operation has a key consumer

* i.e., an input that is explicitly used for the key value.

* This value should correspond to the value returned by `getKeyValueConsumer()`.

*/