Edit the YAML configuration

Learn how to edit the YAML configuration.

5 minute read

The file explorer on your operating system can be used to navigate the user friendly directory structure of a YAML configuration. Any standard text editor can be used to view and edit the individual YAML files.

Ideally, a standard IDE can be used to create a project and edit the files of a YAML configuration. The externalized files for scripts, JSON, etc allow you to edit these files in an editor that is syntax aware.

Use ES Explorer to edit a YAML configuration

ES Explorer can be used with some limitations to view, navigate, and edit a YAML configuration. To connect to a YAML configuration, enter a URL of the form yaml:file:/root/dir/of/yaml.

Create a new policy

Policy Studio is not supported for YAML configuration as yet. Making minor changes to an existing policy or other configuration using an IDE of your choice should be straightforward using an IDE with YAML syntax checking. The yamles validate option should also be used to check the validity of the configuration.

Building a new complex policy without an existing YAML format example may prove challenging. One way to simplify this level of development would be to use the ES Explorer tool, or Policy Studio as follows:

  • Use Policy Studio, or ES Explorer and develop the structure of the policy.
  • Export the policy to a configuration fragment.
  • Convert the XML configuration fragment to YAML using yamles frag2yaml command.
  • Import the YAML configuration fragment into your main YAML project using yamles import command.
  • Repeat the export, frag2yaml and import steps as many times as required to import all the required configuration into your main YAML configuration.

It is recommended to develop a new complex policy in an XML project that contains all the configuration you previously converted to YAML, so that you can reference other existing configuration. You will need to ensure all referenced entities that need to be resolvable can be resolved eventually.

Add a new certificate and private key to a YAML configuration

This section covers the steps required to add a new certificate and private key to an existing YAML configuration. Note that certificates and private keys that exist in the XML federated configuration, which then get converted to YAML format will be formatted as required with no additional steps required. In some cases you might only need to add a new certificate to the YAML configuration, in this case the steps for the private key can be ignored.

You must have a certificate in a PEM file and its related private key in separate DER file, for example, Axway-cert.pem and Axway-key.der. The private key should be unencrypted.

For testing purposes you can generate an unencrypted private key and self-signed certificate PEM files as follows using openssl:

> openssl req -nodes -new -x509 -keyout Axway-key.pem -out Axway-cert.pem
Generating a RSA private key
writing new private key to 'Axway-key.pem'
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code) [AU]:IE
State or Province Name (full name) [Some-State]:Dublin
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Axway
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:Axway
Email Address []:axway@axway.com

Convert the Axway-key.pem to an Axway-key.der as follows:

openssl pkcs8 -topk8 -inform PEM -outform DER -in Axway-key.pem -out Axway-key.der -nocrypt

Copy the Axway-cert.pem and Axway-key.der files into the /Environment Configuration/Certificate Store directory in your YAML entity store.

The Axway-cert.pem file needs a minor modification to allow it to be loaded by the YAML entity store. Edit the Axway-cert.pem file so that the header and footer lines are removed and only the base64 content remains. Remove the following lines from /Environment Configuration/Certificate Store/Axway-cert.pem:


so that the file content looks like this:


Create the following /Environment Configuration/Certificate Store/Axway.yaml file in your YAML entity store:

type: Certificate
  dname: Axway
  key#refbinary: Axway-key.der
  content#ref: Axway-cert.pem

Edit another entity that requires a certificate and private key, for example an XML Signature filter (see the signingCert field below). It now points to the new certificate and private key via its YamlPK /Environment Configuration/Certificate Store/Axway.

type: FilterCircuit
  name: cert
  start: ./XML Signature Generation
- type: GenerateSignatureFilter
    signingCertAttribute: ""
    keyWrapAlgorithm: http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
    symmetricKeyEncryptionCertAttribute: ""
    name: XML Signature Generation
    signingCert: /Environment Configuration/Certificate Store/Axway   # <-- certificate ref
    symmetricKeyAttribute: ""
    - /System/Element Specifiers/http://schemas.xmlsoap.org/soap/envelope/,Body,1
    - /System/Element Specifiers/http://www.w3.org/2003/05/soap-envelope,Body,1
    attachmentTransform: ""
    success: ../XML Signature Verification
    fatal: 'Error during message signing. Error: ${circuit.exception}'
    failure: Failed to sign message
    success: Signed message successfully
  - type: KeyInfoFormat
      keyNameValue: CN
      publicKeyInfoMask: 15
      keyNameType: 2
      certAttachmentId: ""

If the YAML configuration you are adding the certificate and private key into is encrypted with a passphrase, you will need to encrypt the private key file. To encrypt the private key file Axway-key.der, follow all the steps above and complete the procedure with the following:

cd apigateway/posix/bin
./yamles encrypt --file ~/yaml/Environment\ Configuration/Certificate\ Store/Axway-key.der --passphrase changeme
The file `/home/user/yaml/Environment Configuration/Certificate Store/Axway-key.der` has been encrypted

When edits are complete on the YAML configuration, you must create a .tar.gz file and deploy it to your running API Gateway.