Package crystalpalace.spec

Class LinkSpec

  • public class LinkSpec
extends java.lang.Object
    An object that parses and interprets a Crystal Palace specification file.

    Call Parse(java.lang.String, java.lang.String) to create a LinkSpec object.

    Call run(byte[], java.util.Map) to apply a specification file to a DLL (or COFF) and other $ARGUMENTS passed into the environment.

    That's the API. If there's a problem, the API will throw a SpecParseException or a SpecProgramException.

    This class is not thread safe.

    PERFORMANCE NOTE: The first use of this API, running a .spec file with a binary transform (e.g., code mutation, link-time optimization, etc.) will incur a 500ms penalty. This is because the iced library has to load several constants from within our JAR file. Future calls to this API (with or without binary transforms) should resolve quickly (~20ms in my VM environment).

    Author:
    Raphael Mudge

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String author
      the author of this .spec file (if specified)
      protected java.lang.String description
      a description of the tradecraft/technique in this .spec file
      protected java.lang.String name
      the short name of the technique/tradecraft in this .spec file
      protected java.lang.String parent
      the file associated with this spec.
      protected crystalpalace.spec.SpecProgram program
      the execution environment for applying this specification to passed in variables

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected LinkSpec​(crystalpalace.spec.SpecParser parser, java.lang.String parent)
      The constructor for our LinkSpec.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      byte[] buildPic​(java.lang.String arch, java.util.Map vars)
      Act on this specification file's directives.
      java.lang.String getAuthor()
      Return the author of this tradecraft.
      java.lang.String getDescription()
      Return a description of the technique/tradecraft.
      java.lang.String getFile()
      Get the name of the file associated with this .spec.
      java.lang.String getName()
      Return the name of the technique/tradecraft.
      static void main​(java.lang.String[] args)
      The entrypoint to Crystal Palace.
      static LinkSpec Parse​(java.lang.String parent)
      Parse a .spec file and return a ready-to-run LinkSpec object.
      static LinkSpec Parse​(java.lang.String parent, java.lang.String content)
      Parse a .spec file and return a ready-to-run LinkSpec object.
      byte[] run​(byte[] capability, java.util.Map vars)
      Apply this specification file's directives to the passed in parameters.
      byte[] runDll​(byte[] dll_arg, java.util.Map vars)
      Apply this specification file's directives to the passed in parameters.
      byte[] runObject​(byte[] object_arg, java.util.Map vars)
      Apply this specification file's directives to the passed in parameters.
      boolean targets​(java.lang.String arch)
      Check if this specification has this specific target.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • parent

        protected java.lang.String parent
        the file associated with this spec.

      • author

        protected java.lang.String author
        the author of this .spec file (if specified)

      • name

        protected java.lang.String name
        the short name of the technique/tradecraft in this .spec file

      • description

        protected java.lang.String description
        a description of the tradecraft/technique in this .spec file

      • program

        protected crystalpalace.spec.SpecProgram program
        the execution environment for applying this specification to passed in variables

    • Method Detail

      • getFile

        public java.lang.String getFile()
        Get the name of the file associated with this .spec. The files does not actually have to exist. It's set by the API when Parse(java.lang.String, java.lang.String) is called.
        Returns:
        the file associated with this spec.

      • getAuthor

        public java.lang.String getAuthor()
        Return the author of this tradecraft. This value is set with the author "name" command in the .spec file.
        Returns:
        the author value

      • getName

        public java.lang.String getName()
        Return the name of the technique/tradecraft. This value is set with the name "tradecraft name" command in the .spec file.
        Returns:
        the name value

      • getDescription

        public java.lang.String getDescription()
        Return a description of the technique/tradecraft. This value is set with the describe "my technique does this" command in the .spec file.
        Returns:
        the description value

      • targets

        public boolean targets​(java.lang.String arch)
        Check if this specification has this specific target. Valid values include x86, x64.
        Parameters:
        arch - the target architecture to check
        Returns:
        true if the technique has an option to target the specific arch

      • run

        public byte[] run​(byte[] capability,
                  java.util.Map vars)
           throws SpecParseException,
                  SpecProgramException
        Apply this specification file's directives to the passed in parameters.
        Parameters:
        capability - is our Win32 DLL or COFF argument. If it's a DLL, runDll(byte[], java.util.Map) handles the rest. If it's a COFF, runObject(byte[], java.util.Map) handles the rest.
        vars - a mapping of $KEY to byte[] values made available during the application of the specification file. Each key should begin with '$' to be accessible within the spec environment.
        Returns:
        the position-independent code (usually) generated by applying this specification to the arguments
        Throws:
        SpecParseException - if a specification file called run "file.spec" from this specification has syntax errors.
        SpecProgramException - if an error occurs or is detected during the application of this specification file.

      • runDll

        public byte[] runDll​(byte[] dll_arg,
                     java.util.Map vars)
              throws SpecParseException,
                     SpecProgramException
        Apply this specification file's directives to the passed in parameters.
        Parameters:
        dll_arg - our Win32 DLL argument, installed into the environment as $DLL. This value is lightly checked for validity (e.g., MZ/PE headers exist). The architecture of this DLL determines which target to call from the specification file.
        vars - a mapping of $KEY to byte[] values made available during the application of the specification file. Each key should begin with '$' to be accessible within the spec environment.
        Returns:
        the position-independent code (usually) generated by applying this specification to the arguments
        Throws:
        SpecParseException - if a specification file called run "file.spec" from this specification has syntax errors.
        SpecProgramException - if an error occurs or is detected during the application of this specification file.

      • runObject

        public byte[] runObject​(byte[] object_arg,
                        java.util.Map vars)
                 throws SpecParseException,
                        SpecProgramException
        Apply this specification file's directives to the passed in parameters.
        Parameters:
        object_arg - our Win32 COFF argument, installed into the environment as $OBJECT. This value is lightly checked for validity (e.g., valid Machine header value). The architecture of this object determines which target (x86.o, x64.o) to call from the specification file.
        vars - a mapping of $KEY to byte[] values made available during the application of the specification file. Each key should begin with '$' to be accessible within the spec environment.
        Returns:
        the position-independent code (usually) generated by applying this specification to the arguments
        Throws:
        SpecParseException - if a specification file called run "file.spec" from this specification has syntax errors.
        SpecProgramException - if an error occurs or is detected during the application of this specification file.

      • buildPic

        public byte[] buildPic​(java.lang.String arch,
                       java.util.Map vars)
                throws SpecParseException,
                       SpecProgramException
        Act on this specification file's directives. This API differs in purpose from run(byte[],java.util.Map), runDll(byte[],java.util.Map), and runObject(byte[],java.util.Map). Its purpose is to assemble a PIC program from known parts, rather than applying PIC to a user-specified capability implemented as a DLL or COFF.
        Parameters:
        arch - is the target architecture label to act on (e.g., x86 or x64)
        vars - a mapping of $KEY to byte[] values made available during the application of the specification file. Each key should begin with '$' to be accessible within the spec environment.
        Returns:
        the position-independent code generated by executing this specification file.
        Throws:
        SpecParseException - if a specification file called run "file.spec" from this specification has syntax errors.
        SpecProgramException - if an error occurs or is detected during the application of this specification file.

      • Parse

        public static LinkSpec Parse​(java.lang.String parent,
                             java.lang.String content)
                      throws SpecParseException
        Parse a .spec file and return a ready-to-run LinkSpec object.
        Parameters:
        parent - the parent file of this .spec content. Returned by #getFile.
        content - the .spec file content
        Returns:
        a LinkSpec object.
        Throws:
        SpecParseException - if a syntax error or mis-used command is detected

      • Parse

        public static LinkSpec Parse​(java.lang.String parent)
                      throws SpecParseException,
                             java.io.IOException
        Parse a .spec file and return a ready-to-run LinkSpec object.
        Parameters:
        parent - The name of the .spec file to read and parse.
        Returns:
        a LinkSpec object
        Throws:
        SpecParseException - if a syntax error or mis-used command is detected
        java.io.IOException - if we can't read the .spec file

      • main

        public static void main​(java.lang.String[] args)
        The entrypoint to Crystal Palace. This is our main function, does the stuff you know and love.
        Parameters:
        args - the command-line arguments