From 849f57e73ae46061610a7f6810e2126cdfbaa52c Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 14 Mar 2017 19:14:27 -0700 Subject: [PATCH 01/17] Update layouts and assets for consistency --- website/Gemfile | 2 +- website/Gemfile.lock | 6 +- website/Makefile | 2 +- website/packer.json | 2 +- .../assets/stylesheets/_announcement-bnr.scss | 64 ---- .../source/assets/stylesheets/_buttons.scss | 2 +- website/source/assets/stylesheets/_docs.scss | 16 +- .../source/assets/stylesheets/_footer.scss | 83 +---- .../source/assets/stylesheets/_global.scss | 19 - .../source/assets/stylesheets/_header.scss | 96 +++-- .../source/assets/stylesheets/_sidebar.scss | 107 +++++- .../source/assets/stylesheets/_variables.scss | 12 + .../assets/stylesheets/application.scss | 10 +- .../hashicorp-shared/_hashicorp-header.scss | 338 ------------------ .../hashicorp-shared/_hashicorp-sidebar.scss | 284 --------------- .../hashicorp-shared/_hashicorp-utility.scss | 125 ------- .../hashicorp-shared/_project-utility.scss | 56 --- website/source/layouts/layout.erb | 36 +- 18 files changed, 225 insertions(+), 1035 deletions(-) delete mode 100755 website/source/assets/stylesheets/_announcement-bnr.scss delete mode 100755 website/source/assets/stylesheets/hashicorp-shared/_hashicorp-header.scss delete mode 100644 website/source/assets/stylesheets/hashicorp-shared/_hashicorp-sidebar.scss delete mode 100755 website/source/assets/stylesheets/hashicorp-shared/_hashicorp-utility.scss delete mode 100755 website/source/assets/stylesheets/hashicorp-shared/_project-utility.scss diff --git a/website/Gemfile b/website/Gemfile index 08e6fe65e..64551b638 100644 --- a/website/Gemfile +++ b/website/Gemfile @@ -1,3 +1,3 @@ source "https://rubygems.org" -gem "middleman-hashicorp", "0.3.13" +gem "middleman-hashicorp", "0.3.14" diff --git a/website/Gemfile.lock b/website/Gemfile.lock index 0811f6d62..9807e2ee6 100644 --- a/website/Gemfile.lock +++ b/website/Gemfile.lock @@ -6,7 +6,7 @@ GEM minitest (~> 5.1) thread_safe (~> 0.3, >= 0.3.4) tzinfo (~> 1.1) - autoprefixer-rails (6.7.6) + autoprefixer-rails (6.7.7) execjs bootstrap-sass (3.3.7) autoprefixer-rails (>= 5.2.1) @@ -77,7 +77,7 @@ GEM rack (>= 1.4.5, < 2.0) thor (>= 0.15.2, < 2.0) tilt (~> 1.4.1, < 2.0) - middleman-hashicorp (0.3.13) + middleman-hashicorp (0.3.14) bootstrap-sass (~> 3.3) builder (~> 3.2) middleman (~> 3.4) @@ -151,7 +151,7 @@ PLATFORMS ruby DEPENDENCIES - middleman-hashicorp (= 0.3.13) + middleman-hashicorp (= 0.3.14) BUNDLED WITH 1.14.6 diff --git a/website/Makefile b/website/Makefile index 41fcf114e..eb05272f7 100644 --- a/website/Makefile +++ b/website/Makefile @@ -1,4 +1,4 @@ -VERSION?="0.3.13" +VERSION?="0.3.14" website: @echo "==> Starting website in Docker..." diff --git a/website/packer.json b/website/packer.json index b51f63801..4487644a5 100644 --- a/website/packer.json +++ b/website/packer.json @@ -8,7 +8,7 @@ "builders": [ { "type": "docker", - "image": "hashicorp/middleman-hashicorp:0.3.13", + "image": "hashicorp/middleman-hashicorp:0.3.14", "discard": "true", "run_command": ["-d", "-i", "-t", "{{ .Image }}", "/bin/sh"] } diff --git a/website/source/assets/stylesheets/_announcement-bnr.scss b/website/source/assets/stylesheets/_announcement-bnr.scss deleted file mode 100755 index 6fac2624c..000000000 --- a/website/source/assets/stylesheets/_announcement-bnr.scss +++ /dev/null @@ -1,64 +0,0 @@ -// -// announcement bnr -// -------------------------------------------------- - -#announcement-bnr { - height: 40px; - flex-shrink: 0; - background-color: $black; - - a,p{ - font-size: 14px; - color: $white; - line-height: 40px; - margin-bottom: 0; - } - - .link-blue{ - margin-left: 5px; - color: $blue; - font-weight: 600; - } - - .enterprise-logo{ - position: relative; - top: 4px; - - &:hover{ - text-decoration: none; - svg{ - rect{ - fill: $blue; - @include transition(all .1s ease-in); - } - } - } - - svg{ - width: 128px; - fill: $white; - margin-right: 4px; - margin-left: 1px; - - rect{ - @include transition(all .1s ease-in); - } - } - } -} - -@media (max-width: 768px) { - #announcement-bnr { - .tagline{ - display: none; - } - } -} - -@media (max-width: 320px) { - #announcement-bnr { - a,p{ - font-size: 12px; - } - } -} diff --git a/website/source/assets/stylesheets/_buttons.scss b/website/source/assets/stylesheets/_buttons.scss index d663bfbd4..05dde9e46 100755 --- a/website/source/assets/stylesheets/_buttons.scss +++ b/website/source/assets/stylesheets/_buttons.scss @@ -3,13 +3,13 @@ // -------------------------------------------------- .v-btn { + box-shadow: 2px 3px 2px rgba(0,0,0,0.08); display: inline-block; background-color: $white; color: $black; border: 1px solid $black; text-decoration: none; @include transition(color .3s ease-in-out); - @include btn-shadow(); &.lrg { font-size: 18px; diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 3703c2a34..9f8e7d2a2 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -4,6 +4,16 @@ $docs-font-size: 15px; +body.layout-http { + h2 { + margin-top: 150px; + + &:first-of-type { + margin-top: 50px; + } + } +} + body.layout-docs, body.layout-inner, body.layout-downloads, @@ -54,13 +64,13 @@ body.layout-intro { li { a { color: $sidebar-link-color; - font-size: 13px; + font-size: $sidebar-font-size; padding: 10px 0 10px 15px; &:before { - color: $dark-blue; + color: $sidebar-link-color-active; content: '\203A'; - font-size: $docs-font-size; + font-size: $font-size; left: 0; line-height: 100%; opacity: 0.4; diff --git a/website/source/assets/stylesheets/_footer.scss b/website/source/assets/stylesheets/_footer.scss index e72244e21..c9e1f5963 100644 --- a/website/source/assets/stylesheets/_footer.scss +++ b/website/source/assets/stylesheets/_footer.scss @@ -1,75 +1,20 @@ -body.page-sub { - #footer { - padding: 0 0 40px 0; - .col-md-10 { - padding-top: 40px; - border-top: 1px solid $faint-gray; - } - } -} - #footer { - flex-shrink:0; - padding: 64px 0; + ul.footer-links { + li { + a { + color: $footer-link-color; + font-size: $footer-font-size; + font-family: $font-family-open-sans; + text-decoration: none; - .hashicorp-project { - margin-top: 24px; - @include project-by-hashicorp-style(); + &:hover, &:focus, &:active { + background-color: transparent; + color: $footer-link-color-hover; + outline: 0; + } - &:hover { - color: $black; - } - } -} - -.edit-page-link { - position: absolute; - top: -50px; - right: 15px; - z-index: 10; - - a { - text-transform: uppercase; - color: $black; - font-size: 13px; - } -} - -@media (max-width: 992px) { - .footer-links { - display: block; - text-align: center; - - ul { - display: inline-block;; - float: none !important; - } - - .footer-hashi { - display: block; - float: none !important; - } - } -} - -@media (max-width: 414px) { - #footer { - ul { - display: block; - li { - display: block; - float: none; - } - - &.external-links { - li { - svg { - position: relative; - left: 0; - top: 2px; - margin-top: 0; - margin-right: 4px; - } + @media (max-width: 992px) { + text-align: center; } } } diff --git a/website/source/assets/stylesheets/_global.scss b/website/source/assets/stylesheets/_global.scss index 67f13f302..eadb7ae74 100755 --- a/website/source/assets/stylesheets/_global.scss +++ b/website/source/assets/stylesheets/_global.scss @@ -29,25 +29,6 @@ h1 { margin-bottom: 24px; } -//all below styles are overriding corrections for below (min-width: 992px) -//below (min-width: 992px) these styles change -.navbar-nav { - margin: 0; -} - -.navbar-right { - float: right !important; -} - -.navbar-nav > li { - float: left; -} - -.navbar-nav > li > a { - padding-top: 15px; - padding-bottom: 15px; -} - .center { text-align: center; } diff --git a/website/source/assets/stylesheets/_header.scss b/website/source/assets/stylesheets/_header.scss index d0f9138c0..4a985d7a8 100755 --- a/website/source/assets/stylesheets/_header.scss +++ b/website/source/assets/stylesheets/_header.scss @@ -1,39 +1,79 @@ -// -// Header -// - Project Specific -// - edits should be made here -// -------------------------------------------------- - #header { - flex-shrink:0; + // Hamburger menu + .navbar-toggle { + height: $header-height; + margin: 0; + padding-right: 15px; + border-radius: 0; - .navbar-brand { - .logo { - width: $project-logo-width; - padding-left: 50px; - font-size: 0; - text-transform: uppercase; - background: image-url('logo-text.svg') 0 0 no-repeat; - background-position: 0 46%; - background-size: contain; + .icon-bar { + border: 1px solid $black; + border-radius: 0; } } - .by-hashicorp { - @include project-by-hashicorp-style(); - } + // Logo + .navbar-brand { + display: block; + margin: 0; + padding: 0; - .buttons { - margin-top: 2px; //baseline everything - } -} + .logo { + color: $header-link-color; + display: inline-block; + font-family: $font-family-klavika; + font-weight: $font-weight-bold; + font-size: 0; + height: $header-height; + line-height: $header-height; + width: 200px; + padding-left: 64px; + background: image-url('logo-text.svg') 0 0 no-repeat; + background-position: left center; -@media (max-width: 414px) { - #header { - .navbar-brand { - .logo { - width: $project-logo-width * .8; + &:hover, &:focus, &:active { + outline: 0; + text-decoration: none; } } } + + // Nav + ul.nav { + li { + a { + color: $header-link-color; + font-size: $header-font-size; + font-family: $font-family-open-sans; + height: $header-height; + line-height: $header-height; + padding: 0 10px; + margin: 0; + text-decoration: none; + + &:hover, &:focus, &:active { + background-color: transparent; + color: $header-link-color-hover; + outline: 0; + + svg { + fill: $header-link-color-hover; + } + } + + svg { + fill: $header-link-color; + position: relative; + top: 2px; + width: 14px; + height: 14px; + margin-right: 3px; + } + } + } + } + + .buttons { + margin-top: 2px; + } } diff --git a/website/source/assets/stylesheets/_sidebar.scss b/website/source/assets/stylesheets/_sidebar.scss index 198142edd..c3d872939 100644 --- a/website/source/assets/stylesheets/_sidebar.scss +++ b/website/source/assets/stylesheets/_sidebar.scss @@ -1,15 +1,106 @@ -.sidebar { - .sidebar-nav { - li { - a { - color: $black; +.sidebar-overlay { + background: $white; + opacity: 0; + position: fixed; + visibility: hidden; + z-index: 9999; - svg{ - path{ - fill: $black; + top: 0; + left: 0; + right: 0; + bottom: 0; + + &.active { + opacity: 0.3; + visibility: visible; + } +} + +.sidebar { + background-color: $white; + border: none; + display: block; + position: relative; + min-height: 100%; + overflow-y: auto; + overflow-x: hidden; + @include transition(all 0.5s cubic-bezier(0.55, 0, 0.1, 1)); + @include clearfix(); + + .sidebar-divider, .divider { + width: 80%; + height: 1px; + margin: 8px auto; + background-color: #D7D7D7; + } + + .sidebar-header { + position: relative; + margin-bottom: 16px; + } + + .sidebar-image { + background: image-url('logo-text.svg') 0 0 no-repeat; + display: block; + margin: 24px auto 14px auto; + height: 56px; + width: 153px; + } + + .sidebar-nav { + margin: 0; + padding: 0; + text-align: center; + + li { + position: relative; + list-style-type: none; + text-align: center; + + a { + color: $sidebar-link-color; + position: relative; + cursor: pointer; + user-select: none; + font-family: $font-family-open-sans; + font-weight: $font-weight-reg; + font-size: $sidebar-font-size; + + &:hover, &:focus, &:active { + background: transparent; + color: $sidebar-link-color-hover; + outline: 0; + text-decoration: none; + + svg { + fill: $sidebar-link-color-hover; } } + + svg { + fill: $sidebar-link-color; + top: 2px; + width: 14px; + height: 14px; + margin-bottom: -2px; + margin-right: 4px; + } } } } } + +.sidebar { + box-shadow: 0px 2px 25px rgba(0, 0, 0, 0.15); + position: fixed; + width: 0; + z-index: 10000; + + top: 0; + bottom: 0; + right: 0; + + &.open { + width: 280px; + } +} diff --git a/website/source/assets/stylesheets/_variables.scss b/website/source/assets/stylesheets/_variables.scss index e5727e4b7..f90cb82f4 100755 --- a/website/source/assets/stylesheets/_variables.scss +++ b/website/source/assets/stylesheets/_variables.scss @@ -32,8 +32,20 @@ $font-weight-bold: 600; // Body $body-font-color: $gray-darker; +$body-link-color: $dark-blue; // Sidebar +$sidebar-font-size: $font-size - 2; $sidebar-link-color: $body-font-color; $sidebar-link-color-hover: $black; $sidebar-link-color-active: $dark-blue; + +// Header +$header-font-size: $font-size - 2; +$header-link-color: $body-font-color; +$header-link-color-hover: $black; + +// Footer +$footer-font-size: $font-size - 2; +$footer-link-color: $body-font-color; +$footer-link-color-hover: $black; diff --git a/website/source/assets/stylesheets/application.scss b/website/source/assets/stylesheets/application.scss index 6f972dbe7..ba0805b0c 100755 --- a/website/source/assets/stylesheets/application.scss +++ b/website/source/assets/stylesheets/application.scss @@ -1,7 +1,7 @@ @import 'bootstrap-sprockets'; @import 'bootstrap'; -@import url("//fonts.googleapis.com/css?family=Open+Sans:300,400,700|Open+Sans:300,600,400|Ubuntu+Mono"); +@import url("//fonts.googleapis.com/css?family=Open+Sans:400,600"); // Core variables and mixins @import '_variables'; @@ -12,14 +12,10 @@ //Mega Nav @import 'hashicorp/mega-nav'; -// Hashicorp Shared Project Styles -@import 'hashicorp-shared/_hashicorp-utility'; -@import 'hashicorp-shared/_project-utility'; -@import 'hashicorp-shared/_hashicorp-header'; -@import 'hashicorp-shared/_hashicorp-sidebar'; +// Anchor links +@import 'hashicorp/anchor-links'; // Components -@import '_announcement-bnr'; @import '_header'; @import '_footer'; @import '_buttons'; diff --git a/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-header.scss b/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-header.scss deleted file mode 100755 index 16feb0874..000000000 --- a/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-header.scss +++ /dev/null @@ -1,338 +0,0 @@ -// -// Hashicorp header -// - Shared throughout projects -// - Edits should not be made here -// -------------------------------------------------- - -#header{ - position: relative; - margin-bottom: 0; -} - -.navigation { - color: black; - text-rendering: optimizeLegibility; - transition: all 1s ease; - - &.white{ - .navbar-brand { - .logo { - color: white; - } - } - - .main-links, - .external-links { - li > a { - &:hover{ - opacity: 1; - } - } - } - } - - .navbar-toggle{ - height: $header-height; - margin: 0; - border-radius: 0; - .icon-bar{ - border: 1px solid $black; - border-radius: 0; - } - } - - .external-links { - &.white{ - svg path{ - fill: $white; - } - } - - li { - position: relative; - - svg path{ - @include transition( all 300ms ease-in ); - } - - &:hover{ - svg path{ - @include transition( all 300ms ease-in ); - } - } - - @include project-svg-external-links-style(); - - &.download{ - margin-right: 10px; - } - - &.github{ - a{ - margin-right: 0; - } - } - - > a { - padding-left: 12px !important; - svg{ - position: absolute; - left: -8px; - top: 50%; - margin-top: -8px; - width: 14px; - height: 14px; - } - } - } - } - - .main-links{ - margin-right: $nav-margin-right; - } - - .main-links, - .external-links { - &.white{ - li > a { - color: white; - } - } - li > a { - @include hashi-a-style(); - margin: 0 10px; - padding-top: 1px; - line-height: $header-height; - @include project-a-style(); - } - } - - .nav > li > a:hover, .nav > li > a:focus { - background-color: transparent; - @include transition( all 300ms ease-in ); - } -} - -.navbar-brand { - display: block; - height: $header-height; - padding: 0; - margin: 0 10px 0 0; - - .logo{ - display: inline-block; - height: $header-height; - vertical-align:top; - padding: 0; - line-height: $header-height; - padding-left: $project-logo-width + $project-logo-pad-left; - background-position: 0 center; - @include transition(all 300ms ease-in); - - &:hover{ - @include transition(all 300ms ease-in); - text-decoration: none; - } - } -} - -.navbar-toggle{ - &.white{ - .icon-bar{ - border: 1px solid white; - } - } -} - -.by-hashicorp{ - display: inline-block; - vertical-align:top; - height: $header-height; - margin-left: 3px; - padding-top: 2px; - color: black; - line-height: $header-height; - font-family: $header-font-family; - font-weight: 600; - font-size: 0; - text-decoration: none; - - &.white{ - color: white; - font-weight: 300; - svg{ - path, - polygon{ - fill: white; - } - } - - &:focus, - &:hover{ - text-decoration: none; - color: white; - } - } - - &:focus, - &:hover{ - text-decoration: none; - color: black; - } - - .svg-wrap{ - font-size: 13px; - } - - svg{ - &.svg-by{ - width: $by-hashicorp-width; - height: $by-hashicorp-height; - margin-bottom: -4px; - margin-left: 4px; - } - - &.svg-logo{ - width: 16px; - height: 16px; - margin-bottom: -3px; - margin-left: 4px; - } - - path, - polygon{ - fill: black; - @include transition(all 300ms ease-in); - - &:hover{ - @include transition(all 300ms ease-in); - } - } - .svg-bg-line{ - @include transition(all 300ms ease-in); - - &:hover{ - @include transition(all 300ms ease-in); - } - } - } -} - -.hashicorp-project{ - display: inline-block; - height: 30px; - line-height: 30px; - text-decoration: none; - font-size: 14px; - color: $black; - font-weight: 600; - - &.white{ - color: white; - svg{ - path, - polygon{ - fill: white; - } - line{ - stroke: white; - } - } - } - - &:focus{ - text-decoration: none; - } - - &:hover{ - text-decoration: none; - svg{ - &.svg-by{ - line{ - stroke: $purple; - } - } - } - } - - span{ - margin-right: 4px; - font-family: $header-font-family; - font-weight: 500; - } - - span, - svg{ - display: inline-block; - } - - svg{ - &.svg-by{ - width: $by-hashicorp-width; - height: $by-hashicorp-height; - margin-bottom: -4px; - margin-left: -3px; - } - - &.svg-logo{ - width: 30px; - height: 30px; - margin-bottom: -10px; - margin-left: -1px; - } - - path, - line{ - fill: $black; - @include transition(all 300ms ease-in); - - &:hover{ - @include transition(all 300ms ease-in); - } - } - .svg-bg-line{ - @include transition(all 300ms ease-in); - - &:hover{ - @include transition(all 300ms ease-in); - } - } - } -} - -@media (max-width: 480px) { - .navigation { - .main-links{ - margin-right: 0; - } - } -} - -@media (max-width: 414px) { - #header { - .navbar-toggle{ - padding-top: 10px; - height: $header-mobile-height; - } - - .navbar-brand { - height: $header-mobile-height; - - .logo{ - height: $header-mobile-height; - line-height: $header-mobile-height; - } - .by-hashicorp{ - height: $header-mobile-height; - line-height: $header-mobile-height; - padding-top: 0; - } - } - .main-links, - .external-links { - li > a { - line-height: $header-mobile-height; - } - } - } -} diff --git a/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-sidebar.scss b/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-sidebar.scss deleted file mode 100644 index 5af9e0bf5..000000000 --- a/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-sidebar.scss +++ /dev/null @@ -1,284 +0,0 @@ -// -// Hashicorp Sidebar -// - Shared throughout projects -// - Edits should not be made here -// -------------------------------------------------- - -// Base variables -// -------------------------------------------------- -$screen-tablet: 768px; - -$gray-darker: #212121; // #212121 - text -$gray-secondary: #757575; // #757575 - secondary text, icons -$gray: #bdbdbd; // #bdbdbd - hint text -$gray-light: #e0e0e0; // #e0e0e0 - divider -$gray-lighter: #f5f5f5; // #f5f5f5 - background -$link-color: $gray-darker; -$link-bg: transparent; -$link-hover-color: $gray-lighter; -$link-hover-bg: $gray-lighter; -$link-active-color: $gray-darker; -$link-active-bg: $gray-light; -$link-disabled-color: $gray-light; -$link-disabled-bg: transparent; - -/* -- Sidebar style ------------------------------- */ - -// Sidebar variables -// -------------------------------------------------- -$zindex-sidebar-fixed: 1035; - -$sidebar-desktop-width: 280px; -$sidebar-width: 240px; - -$sidebar-padding: 16px; -$sidebar-divider: $sidebar-padding/2; - -$sidebar-icon-width: 40px; -$sidebar-icon-height: 20px; - -@mixin sidebar-nav-base { - text-align: center; - - &:last-child{ - border-bottom: none; - } - - li > a { - background-color: $link-bg; - } - - li:hover > a { - background-color: $link-hover-bg; - } - - li:focus > a, li > a:focus { - background-color: $link-bg; - } - - > .open > a { - &, - &:hover, - &:focus { - background-color: $link-hover-bg; - } - } - - > .active > a { - &, - &:hover, - &:focus { - background-color: $link-active-bg; - } - } - > .disabled > a { - &, - &:hover, - &:focus { - background-color: $link-disabled-bg; - } - } - - // Dropdown menu items - > .dropdown { - // Remove background color from open dropdown - > .dropdown-menu { - background-color: $link-hover-bg; - - > li > a { - &:focus { - background-color: $link-hover-bg; - } - &:hover { - background-color: $link-hover-bg; - } - } - - > .active > a { - &, - &:hover, - &:focus { - color: $link-active-color; - background-color: $link-active-bg; - } - } - } - } -} - -// -// Sidebar -// -------------------------------------------------- - -// Sidebar Elements -// -// Basic style of sidebar elements -.sidebar { - position: relative; - display: block; - min-height: 100%; - overflow-y: auto; - overflow-x: hidden; - border: none; - @include transition(all 0.5s cubic-bezier(0.55, 0, 0.1, 1)); - @include clearfix(); - background-color: $white; - - ul{ - padding-left: 0; - list-style-type: none; - } - - .sidebar-divider, .divider { - width: 80%; - height: 1px; - margin: 8px auto; - background-color: lighten($gray, 20%); - } - - // Sidebar heading - //---------------- - .sidebar-header { - position: relative; - margin-bottom: $sidebar-padding; - @include transition(all .2s ease-in-out); - } - - .sidebar-image { - background-image: image-url('logo-text.svg'); - background-position: center center; - background-repeat: no-repeat; - height: 72px; - margin-top: 24px; - } - - - // Sidebar icons - //---------------- - .sidebar-icon { - display: inline-block; - height: $sidebar-icon-height; - margin-right: $sidebar-divider; - text-align: left; - font-size: $sidebar-icon-height; - vertical-align: middle; - - &:before, &:after { - vertical-align: middle; - } - } - - .sidebar-nav { - margin: 0; - padding: 0; - - @include sidebar-nav-base(); - - // Links - //---------------- - li { - position: relative; - list-style-type: none; - text-align: center; - - a { - position: relative; - cursor: pointer; - user-select: none; - @include hashi-a-style-core(); - - svg{ - top: 2px; - width: 14px; - height: 14px; - margin-bottom: -2px; - margin-right: 4px; - } - } - } - } -} - -// Sidebar toggling -// -// Hide sidebar -.sidebar { - width: 0; - @include translate3d(-$sidebar-desktop-width, 0, 0); - - &.open { - min-width: $sidebar-desktop-width; - width: $sidebar-desktop-width; - @include translate3d(0, 0, 0); - } -} - -// Sidebar positions: fix the left/right sidebars -.sidebar-fixed-left, -.sidebar-fixed-right, -.sidebar-stacked { - position: fixed; - top: 0; - bottom: 0; - z-index: $zindex-sidebar-fixed; -} -.sidebar-stacked { - left: 0; -} -.sidebar-fixed-left { - left: 0; - box-shadow: 2px 0px 25px rgba(0,0,0,0.15); - -webkit-box-shadow: 2px 0px 25px rgba(0,0,0,0.15); -} -.sidebar-fixed-right { - right: 0; - box-shadow: 0px 2px 25px rgba(0,0,0,0.15); - -webkit-box-shadow: 0px 2px 25px rgba(0,0,0,0.15); - - @include translate3d($sidebar-desktop-width, 0, 0); - &.open { - @include translate3d(0, 0, 0); - } - .icon-material-sidebar-arrow:before { - content: "\e614"; // icon-material-arrow-forward - } -} - -// Sidebar size -// -// Change size of sidebar and sidebar elements on small screens -@media (max-width: $screen-tablet) { - .sidebar.open { - min-width: $sidebar-width; - width: $sidebar-width; - } -} - -.sidebar-overlay { - visibility: hidden; - position: fixed; - top: 0; - left: 0; - right: 0; - bottom: 0; - opacity: 0; - background: $white; - z-index: $zindex-sidebar-fixed - 1; - - -webkit-transition: visibility 0 linear .4s,opacity .4s cubic-bezier(.4,0,.2,1); - -moz-transition: visibility 0 linear .4s,opacity .4s cubic-bezier(.4,0,.2,1); - transition: visibility 0 linear .4s,opacity .4s cubic-bezier(.4,0,.2,1); - -webkit-transform: translateZ(0); - -moz-transform: translateZ(0); - -ms-transform: translateZ(0); - -o-transform: translateZ(0); - transform: translateZ(0); -} - -.sidebar-overlay.active { - opacity: 0.3; - visibility: visible; - -webkit-transition-delay: 0; - -moz-transition-delay: 0; - transition-delay: 0; -} diff --git a/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-utility.scss b/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-utility.scss deleted file mode 100755 index a8764ae30..000000000 --- a/website/source/assets/stylesheets/hashicorp-shared/_hashicorp-utility.scss +++ /dev/null @@ -1,125 +0,0 @@ -// -// Hashicorp Nav (header/footer) Utiliy Vars and Mixins -// -// Notes: -// - Include this in Application.scss before header and feature-footer -// - Open Sans Google (Semibold - 600) font needs to be included if not already -// -------------------------------------------------- - -// Variables -$font-family-open-sans: 'Open Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif; -$header-font-family: $font-family-open-sans; -$header-font-weight: 600; // semi-bold - -$header-height: 74px; -$header-mobile-height: 60px; -$by-hashicorp-width: 74px; -$by-hashicorp-height: 16px; -$nav-margin-right: 8px; - -// Mixins -@mixin hashi-a-style-core{ - font-family: $header-font-family; - font-weight: $header-font-weight; - font-size: 14px; - //letter-spacing: 0.0625em; -} - -@mixin hashi-a-style{ - margin: 0 15px; - padding: 0; - line-height: 22px; - @include hashi-a-style-core(); - @include transition( all 0.3s ease ); - - &:hover{ - @include transition( all 0.3s ease ); - background-color: transparent; - } -} - -@mixin v-nav-style{ - margin: 0 15px; - padding: 0; - line-height: 26px; - color: #2E2E2E; - font-size: 14px; - font-weight: 400; - @include transition( color 0.3s ease ); - - &:hover{ - color: $blue; - @include transition( color 0.3s ease ); - background-color: transparent; - } -} - -//general shared project mixins -@mixin img-retina($image1x, $image, $width, $height) { - background-image: image-url($image1x); - background-size: $width $height; - background-repeat: no-repeat; - - @media (min--moz-device-pixel-ratio: 1.3), - (-o-min-device-pixel-ratio: 2.6/2), - (-webkit-min-device-pixel-ratio: 1.3), - (min-device-pixel-ratio: 1.3), - (min-resolution: 1.3dppx) { - /* on retina, use image that's scaled by 2 */ - background-image: image-url($image); - background-size: $width $height; - } -} - -//wrapper for img-retina when using pngs -@mixin img-ret-rails-jpg($img-name, $width, $height){ - @include img-retina( asset_path('#{$imagePath}#{$img-name}.jpg'), asset_path('#{$imagePath}#{$img-name}@2x.jpg'), $width, $height); -} - -@mixin img-ret-rails-png($img-name, $width, $height){ - @include img-retina( asset_path('#{$imagePath}#{$img-name}.png'), asset_path('#{$imagePath}#{$img-name}@2x.png'), $width, $height); -} - - -@mixin skewY($skew) { - -webkit-transform: skewY($skew); - -moz-transform: skewY($skew); - -ms-transform: skewY($skew); - -o-transform: skewY($skew); - transform: skewY($skew); -} - -// -// ------------------------- -@mixin anti-alias() { - text-rendering: optimizeLegibility; - -webkit-font-smoothing: antialiased; -} - -@mixin open-light() { - font-family: $font-family-open-sans; - font-weight: 300; -} - -@mixin open() { - font-family: $font-family-open-sans; - font-weight: 400; -} - -@mixin open-sb() { - font-family: $font-family-open-sans; - font-weight: 600; -} - -@mixin open-bold() { - font-family: $font-family-open-sans; - font-weight: 700; -} - -@mixin bez-1-transition{ - @include transition( all 300ms ease-in-out ); -} - -@mixin btn-shadow{ - box-shadow: 2px 3px 2px rgba(0,0,0,0.08); -} diff --git a/website/source/assets/stylesheets/hashicorp-shared/_project-utility.scss b/website/source/assets/stylesheets/hashicorp-shared/_project-utility.scss deleted file mode 100755 index 3ed4796a2..000000000 --- a/website/source/assets/stylesheets/hashicorp-shared/_project-utility.scss +++ /dev/null @@ -1,56 +0,0 @@ -// -// Mixins Specific to project -// - make edits to mixins here -// -------------------------------------------------- - -// Variables - -$header-font-family: $font-family-open-sans; -$project-logo-width: 121px; -$project-logo-height: 42px; -$project-logo-pad-left: 0px; - -$blue: darken($blue, 5%); - -// Mixins -@mixin project-a-style{ - font-size: 14px; - font-weight: 400; - color: $gray; - - &:hover{ - color: $blue; - } -} - -@mixin project-footer-a-style{ - &:hover{ - - } -} - -@mixin project-svg-external-links-style{ - svg path{ - fill: $black; - } - - &:hover{ - svg path{ - fill: $blue; - } - } -} - -@mixin project-by-hashicorp-style{ - @include transition(all 300ms ease-in); - - &:hover{ - @include transition(all 300ms ease-in); - - svg{ - .svg-bg-line{ - fill: $black; - } - } - } -} diff --git a/website/source/layouts/layout.erb b/website/source/layouts/layout.erb index 32c8a62ce..ec2529730 100644 --- a/website/source/layouts/layout.erb +++ b/website/source/layouts/layout.erb @@ -89,33 +89,15 @@
- <% if current_page.url != '/' && current_page.url != '/index.html' %> -
Edit this page
- <% end %> -
- - -
-
- - A - <%= partial "layouts/svg/svg-by-hashicorp" %> - Project - <%= partial "layouts/svg/svg-hashicorp-logo" %> - -
+ +
From cd4bcc9c00ea19bf9226bda1d94e01fe9b2fed5a Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 14 Mar 2017 23:41:27 -0700 Subject: [PATCH 02/17] Allow nested code in li to receive new highlighting --- website/source/assets/stylesheets/_docs.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 9f8e7d2a2..50911210d 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -40,7 +40,7 @@ body.layout-intro { h4 > code, h5 > code h6 > code, - li > code, + li code, table code, p code, tt, From db4f689009318b99e56e49661061e0c2b1d0afb1 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 14 Mar 2017 23:41:42 -0700 Subject: [PATCH 03/17] Do not have a large margin --- website/source/assets/stylesheets/_docs.scss | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 50911210d..9518ab0e2 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -4,16 +4,6 @@ $docs-font-size: 15px; -body.layout-http { - h2 { - margin-top: 150px; - - &:first-of-type { - margin-top: 50px; - } - } -} - body.layout-docs, body.layout-inner, body.layout-downloads, From a80e0695be5270a532681c753fd0fbac74db18b5 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Wed, 15 Mar 2017 23:43:36 -0700 Subject: [PATCH 04/17] Update middleman version --- website/Gemfile | 2 +- website/Gemfile.lock | 4 ++-- website/Makefile | 2 +- website/packer.json | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/Gemfile b/website/Gemfile index 64551b638..3b04441c6 100644 --- a/website/Gemfile +++ b/website/Gemfile @@ -1,3 +1,3 @@ source "https://rubygems.org" -gem "middleman-hashicorp", "0.3.14" +gem "middleman-hashicorp", "0.3.15" diff --git a/website/Gemfile.lock b/website/Gemfile.lock index 9807e2ee6..6c816d6d5 100644 --- a/website/Gemfile.lock +++ b/website/Gemfile.lock @@ -77,7 +77,7 @@ GEM rack (>= 1.4.5, < 2.0) thor (>= 0.15.2, < 2.0) tilt (~> 1.4.1, < 2.0) - middleman-hashicorp (0.3.14) + middleman-hashicorp (0.3.15) bootstrap-sass (~> 3.3) builder (~> 3.2) middleman (~> 3.4) @@ -151,7 +151,7 @@ PLATFORMS ruby DEPENDENCIES - middleman-hashicorp (= 0.3.14) + middleman-hashicorp (= 0.3.15) BUNDLED WITH 1.14.6 diff --git a/website/Makefile b/website/Makefile index eb05272f7..e9a70a8fa 100644 --- a/website/Makefile +++ b/website/Makefile @@ -1,4 +1,4 @@ -VERSION?="0.3.14" +VERSION?="0.3.15" website: @echo "==> Starting website in Docker..." diff --git a/website/packer.json b/website/packer.json index 4487644a5..d286e6ef5 100644 --- a/website/packer.json +++ b/website/packer.json @@ -8,7 +8,7 @@ "builders": [ { "type": "docker", - "image": "hashicorp/middleman-hashicorp:0.3.14", + "image": "hashicorp/middleman-hashicorp:0.3.15", "discard": "true", "run_command": ["-d", "-i", "-t", "{{ .Image }}", "/bin/sh"] } From 19b2b049c34e2ea80d3d8438251f0594488c50d7 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Tue, 14 Mar 2017 23:40:33 -0700 Subject: [PATCH 05/17] Redo docs for system backend This commit updates the API documentation for the system backend to break things apart on a per-page basis and provide specific examples. This pattern will give more flexibility for future documentation as well. --- website/source/assets/stylesheets/_api.scss | 9 + .../source/docs/http/sys-audit-hash.html.md | 53 ---- website/source/docs/http/sys-audit.html.md | 110 -------- website/source/docs/http/sys-auth.html.md | 182 ------------- .../http/sys-capabilities-accessor.html.md | 48 ---- .../docs/http/sys-capabilities-self.html.md | 44 --- .../source/docs/http/sys-capabilities.html.md | 48 ---- .../docs/http/sys-config-auditing.html.md | 133 ---------- .../docs/http/sys-generate-root.html.md | 188 ------------- website/source/docs/http/sys-health.html.md | 81 ------ website/source/docs/http/sys-init.html.md | 130 --------- .../source/docs/http/sys-key-status.html.md | 38 --- website/source/docs/http/sys-leader.html.md | 37 --- website/source/docs/http/sys-mounts.html.md | 203 -------------- website/source/docs/http/sys-policy.html.md | 126 --------- website/source/docs/http/sys-raw.html.md | 96 ------- website/source/docs/http/sys-rekey.html.md | 251 ------------------ website/source/docs/http/sys-remount.html.md | 39 --- website/source/docs/http/sys-renew.html.md | 44 --- .../source/docs/http/sys-revoke-force.html.md | 36 --- .../docs/http/sys-revoke-prefix.html.md | 32 --- website/source/docs/http/sys-revoke.html.md | 29 -- website/source/docs/http/sys-rotate.html.md | 37 --- .../source/docs/http/sys-seal-status.html.md | 54 ---- website/source/docs/http/sys-seal.html.md | 30 --- .../source/docs/http/sys-step-down.html.md | 33 --- website/source/docs/http/sys-unseal.html.md | 44 --- .../docs/http/sys-wrapping-lookup.html.md | 54 ---- .../docs/http/sys-wrapping-rewrap.html.md | 60 ----- .../docs/http/sys-wrapping-unwrap.html.md | 65 ----- .../docs/http/sys-wrapping-wrap.html.md | 59 ---- .../docs/http/system/audit-hash.html.md | 63 +++++ website/source/docs/http/system/audit.html.md | 118 ++++++++ website/source/docs/http/system/auth.html.md | 193 ++++++++++++++ .../http/system/capabilities-accessor.html.md | 57 ++++ .../http/system/capabilities-self.html.md | 54 ++++ .../docs/http/system/capabilities.html.md | 56 ++++ .../docs/http/system/config-auditing.html.md | 130 +++++++++ .../docs/http/system/generate-root.html.md | 170 ++++++++++++ .../source/docs/http/system/health.html.md | 71 +++++ website/source/docs/http/system/index.html.md | 17 ++ website/source/docs/http/system/init.html.md | 112 ++++++++ .../docs/http/system/key-status.html.md | 37 +++ .../source/docs/http/system/leader.html.md | 39 +++ .../source/docs/http/system/mounts.html.md | 188 +++++++++++++ .../source/docs/http/system/policy.html.md | 121 +++++++++ website/source/docs/http/system/raw.html.md | 100 +++++++ website/source/docs/http/system/rekey.html.md | 217 +++++++++++++++ .../source/docs/http/system/remount.html.md | 44 +++ website/source/docs/http/system/renew.html.md | 68 +++++ .../docs/http/system/revoke-force.html.md | 43 +++ .../docs/http/system/revoke-prefix.html.md | 38 +++ .../source/docs/http/system/revoke.html.md | 32 +++ .../source/docs/http/system/rotate.html.md | 31 +++ .../docs/http/system/seal-status.html.md | 55 ++++ website/source/docs/http/system/seal.html.md | 30 +++ .../source/docs/http/system/step-down.html.md | 33 +++ .../source/docs/http/system/unseal.html.md | 78 ++++++ .../docs/http/system/wrapping-lookup.html.md | 57 ++++ .../docs/http/system/wrapping-rewrap.html.md | 64 +++++ .../docs/http/system/wrapping-unwrap.html.md | 69 +++++ .../docs/http/system/wrapping-wrap.html.md | 66 +++++ 62 files changed, 2460 insertions(+), 2384 deletions(-) delete mode 100644 website/source/docs/http/sys-audit-hash.html.md delete mode 100644 website/source/docs/http/sys-audit.html.md delete mode 100644 website/source/docs/http/sys-auth.html.md delete mode 100644 website/source/docs/http/sys-capabilities-accessor.html.md delete mode 100644 website/source/docs/http/sys-capabilities-self.html.md delete mode 100644 website/source/docs/http/sys-capabilities.html.md delete mode 100644 website/source/docs/http/sys-config-auditing.html.md delete mode 100644 website/source/docs/http/sys-generate-root.html.md delete mode 100644 website/source/docs/http/sys-health.html.md delete mode 100644 website/source/docs/http/sys-init.html.md delete mode 100644 website/source/docs/http/sys-key-status.html.md delete mode 100644 website/source/docs/http/sys-leader.html.md delete mode 100644 website/source/docs/http/sys-mounts.html.md delete mode 100644 website/source/docs/http/sys-policy.html.md delete mode 100644 website/source/docs/http/sys-raw.html.md delete mode 100644 website/source/docs/http/sys-rekey.html.md delete mode 100644 website/source/docs/http/sys-remount.html.md delete mode 100644 website/source/docs/http/sys-renew.html.md delete mode 100644 website/source/docs/http/sys-revoke-force.html.md delete mode 100644 website/source/docs/http/sys-revoke-prefix.html.md delete mode 100644 website/source/docs/http/sys-revoke.html.md delete mode 100644 website/source/docs/http/sys-rotate.html.md delete mode 100644 website/source/docs/http/sys-seal-status.html.md delete mode 100644 website/source/docs/http/sys-seal.html.md delete mode 100644 website/source/docs/http/sys-step-down.html.md delete mode 100644 website/source/docs/http/sys-unseal.html.md delete mode 100644 website/source/docs/http/sys-wrapping-lookup.html.md delete mode 100644 website/source/docs/http/sys-wrapping-rewrap.html.md delete mode 100644 website/source/docs/http/sys-wrapping-unwrap.html.md delete mode 100644 website/source/docs/http/sys-wrapping-wrap.html.md create mode 100644 website/source/docs/http/system/audit-hash.html.md create mode 100644 website/source/docs/http/system/audit.html.md create mode 100644 website/source/docs/http/system/auth.html.md create mode 100644 website/source/docs/http/system/capabilities-accessor.html.md create mode 100644 website/source/docs/http/system/capabilities-self.html.md create mode 100644 website/source/docs/http/system/capabilities.html.md create mode 100644 website/source/docs/http/system/config-auditing.html.md create mode 100644 website/source/docs/http/system/generate-root.html.md create mode 100644 website/source/docs/http/system/health.html.md create mode 100644 website/source/docs/http/system/index.html.md create mode 100644 website/source/docs/http/system/init.html.md create mode 100644 website/source/docs/http/system/key-status.html.md create mode 100644 website/source/docs/http/system/leader.html.md create mode 100644 website/source/docs/http/system/mounts.html.md create mode 100644 website/source/docs/http/system/policy.html.md create mode 100644 website/source/docs/http/system/raw.html.md create mode 100644 website/source/docs/http/system/rekey.html.md create mode 100644 website/source/docs/http/system/remount.html.md create mode 100644 website/source/docs/http/system/renew.html.md create mode 100644 website/source/docs/http/system/revoke-force.html.md create mode 100644 website/source/docs/http/system/revoke-prefix.html.md create mode 100644 website/source/docs/http/system/revoke.html.md create mode 100644 website/source/docs/http/system/rotate.html.md create mode 100644 website/source/docs/http/system/seal-status.html.md create mode 100644 website/source/docs/http/system/seal.html.md create mode 100644 website/source/docs/http/system/step-down.html.md create mode 100644 website/source/docs/http/system/unseal.html.md create mode 100644 website/source/docs/http/system/wrapping-lookup.html.md create mode 100644 website/source/docs/http/system/wrapping-rewrap.html.md create mode 100644 website/source/docs/http/system/wrapping-unwrap.html.md create mode 100644 website/source/docs/http/system/wrapping-wrap.html.md diff --git a/website/source/assets/stylesheets/_api.scss b/website/source/assets/stylesheets/_api.scss index 5bc1dc2a1..4a3d65465 100644 --- a/website/source/assets/stylesheets/_api.scss +++ b/website/source/assets/stylesheets/_api.scss @@ -2,6 +2,15 @@ // API // -------------------------------------------------- +body.layout-http { + // Extend bootstrap's table and table-striped classes on generic markdown + // tables. This enables GHFM tables instead of HTML. + table { + @extend .table; + @extend .table-striped; + } +} + .bs-api-section dl, dl.api { margin-top: 30px; line-height: 20px; diff --git a/website/source/docs/http/sys-audit-hash.html.md b/website/source/docs/http/sys-audit-hash.html.md deleted file mode 100644 index d4dcc8c37..000000000 --- a/website/source/docs/http/sys-audit-hash.html.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/audit-hash" -sidebar_current: "docs-http-audits-hash" -description: |- - The `/sys/audit-hash` endpoint is used to hash data using an audit backend's hash function and salt. ---- - -# /sys/audit-hash - -## POST - -
-
Description
-
- Hash the given input data with the specified audit backend's hash function - and salt. This endpoint can be used to discover whether a given plaintext - string (the `input` parameter) appears in the audit log in obfuscated form. - Note that the audit log records requests and responses; since the Vault API - is JSON-based, any binary data returned from an API call (such as a - DER-format certificate) is base64-encoded by the Vault server in the - response, and as a result such information should also be base64-encoded to - supply into the `input` parameter. -
- -
Method
-
POST
- -
URL
-
`/sys/audit-hash/`
- -
Parameters
-
-
    -
  • - input - required - The input string to hash. -
    • -
-
- -
Returns
-
- - ```javascript - { - "hash": "hmac-sha256:08ba357e274f528065766c770a639abf6809b39ccfd37c2a3157c7f51954da0a" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-audit.html.md b/website/source/docs/http/sys-audit.html.md deleted file mode 100644 index 3d494155b..000000000 --- a/website/source/docs/http/sys-audit.html.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/audit" -sidebar_current: "docs-http-audits-audits" -description: |- - The `/sys/audit` endpoint is used to enable and disable audit backends. ---- - -# /sys/audit - -## GET - -
-
Description
-
- List the mounted audit backends. _This endpoint requires `sudo` - capability._ -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "file": { - "type": "file", - "description": "Store logs in a file", - "options": { - "path": "/var/log/file" - } - } - } - ``` - -
-
- -## PUT - -
-
Description
-
- Enable an audit backend. _This endpoint requires `sudo` capability._ -
- -
Method
-
PUT
- -
URL
-
`/sys/audit/`
- -
Parameters
-
-
    -
  • - type - required - The type of the audit backend. -
    • -
  • - description - optional - A description of the audit backend for operators. -
    • -
  • - options - optional - An object of options to configure the backend. This is - dependent on the backend type. Please consult the documentation - for the backend type you intend to use. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Disable the given audit backend. _This endpoint requires `sudo` - capability._ -
- -
Method
-
DELETE
- -
URL
-
`/sys/audit/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-auth.html.md b/website/source/docs/http/sys-auth.html.md deleted file mode 100644 index e60ea8871..000000000 --- a/website/source/docs/http/sys-auth.html.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/auth" -sidebar_current: "docs-http-auth-auth" -description: |- - The `/sys/auth` endpoint is used to manage auth backends in Vault. ---- - -# /sys/auth - -## GET - -
-
Description
-
- Lists all the enabled auth backends. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "github": { - "type": "github", - "description": "GitHub auth" - } - } - ``` - -
-
- -## POST - -
-
Description
-
- Enable a new auth backend. The auth backend can be accessed and configured - via the auth path specified in the URL. This auth path will be exposed - under the `auth` prefix. For example, enabling with the `/sys/auth/foo` URL - will make the backend available at `/auth/foo`. _This endpoint requires - `sudo` capability on the final path._ -
- -
Method
-
POST
- -
URL
-
`/sys/auth/`
- -
Parameters
-
-
    -
  • - type - required - The name of the auth backend type, such as "github" -
    • -
  • - description - optional - A human-friendly description of the auth backend. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Disable the auth backend at the given auth path. _This endpoint requires - `sudo` capability on the final path._ -
- -
Method
-
DELETE
- -
URL
-
`/sys/auth/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/auth/[auth-path]/tune - -## GET - -
-
Description
-
- Read the given auth path's configuration. Returns the current time - in seconds for each TTL, which may be the system default or a auth path - specific value. _This endpoint requires `sudo` capability on the final - path, but the same functionality can be achieved without `sudo` via - `sys/mounts/auth/[auth-path]/tune`._ -
- -
Method
-
GET
- -
URL
-
`/sys/auth/[auth-path]/tune`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "default_lease_ttl": 3600, - "max_lease_ttl": 7200 - } - ``` - -
-
- -## POST - -
-
Description
-
- Tune configuration parameters for a given auth path. _This endpoint - requires `sudo` capability on the final path, but the same functionality - can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._ -
- -
Method
-
POST
- -
URL
-
`/sys/auth/[auth-path]/tune`
- -
Parameters
-
-
    -
  • - default_lease_ttl - optional - The default time-to-live. If set on a specific auth path, - overrides the global default. A value of "system" or "0" - are equivalent and set to the system default TTL. -
    • -
  • - max_lease_ttl - optional - The maximum time-to-live. If set on a specific auth path, - overrides the global default. A value of "system" or "0" - are equivalent and set to the system max TTL. -
    • -
-
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-capabilities-accessor.html.md b/website/source/docs/http/sys-capabilities-accessor.html.md deleted file mode 100644 index c707ddf61..000000000 --- a/website/source/docs/http/sys-capabilities-accessor.html.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/capabilities-accessor" -sidebar_current: "docs-http-auth-capabilities-accessor" -description: |- - The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of the token associated with an accessor, on the given path. ---- - -# /sys/capabilities-accessor - -## POST - -
-
Description
-
- Returns the capabilities of the token associated with an accessor, on the given path. -
- -
Method
-
POST
- -
Parameters
-
-
    -
  • - accessor - required - Accessor of the token. -
    • -
  • - path - required - Path on which the token's capabilities will be checked. -
    • -
-
- -
Returns
-
- - ```javascript - { - "capabilities": ["read", "list"] - } - ``` - -
-
diff --git a/website/source/docs/http/sys-capabilities-self.html.md b/website/source/docs/http/sys-capabilities-self.html.md deleted file mode 100644 index f581da5f3..000000000 --- a/website/source/docs/http/sys-capabilities-self.html.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/capabilities-self" -sidebar_current: "docs-http-auth-capabilities-self" -description: |- - The `/sys/capabilities-self` endpoint is used to fetch the capabilities of client token on a given path. ---- - -# /sys/capabilities-self - -## POST - -
-
Description
-
- Returns the capabilities of client token on the given path. - Client token is the Vault token with which this API call is made. -
- -
Method
-
POST
- -
Parameters
-
-
    -
  • - path - required - Path on which the client token's capabilities will be checked. -
    • -
-
- -
Returns
-
- - ```javascript - { - "capabilities": ["read", "list"] - } - ``` - -
-
diff --git a/website/source/docs/http/sys-capabilities.html.md b/website/source/docs/http/sys-capabilities.html.md deleted file mode 100644 index 0375bb515..000000000 --- a/website/source/docs/http/sys-capabilities.html.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/capabilities" -sidebar_current: "docs-http-auth-capabilities" -description: |- - The `/sys/capabilities` endpoint is used to fetch the capabilities of a token on a given path. ---- - -# /sys/capabilities - -## POST - -
-
Description
-
- Returns the capabilities of the token on the given path. -
- -
Method
-
POST
- -
Parameters
-
-
    -
  • - token - required - Token for which capabilities are being queried. -
    • -
  • - path - required - Path on which the token's capabilities will be checked. -
    • -
-
- -
Returns
-
- - ```javascript - { - "capabilities": ["read", "list"] - } - ``` - -
-
diff --git a/website/source/docs/http/sys-config-auditing.html.md b/website/source/docs/http/sys-config-auditing.html.md deleted file mode 100644 index 36bfda836..000000000 --- a/website/source/docs/http/sys-config-auditing.html.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/config/auditing" -sidebar_current: "docs-http-config-auditing" -description: |- - The `/sys/config/auditing` endpoint is used to configure auditing settings. ---- - -# /sys/config/auditing/request-headers - -## GET - -
-
Description
-
- List the request headers that are configured to be audited. _This endpoint requires `sudo` - capability._ -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "headers": { - "X-Forwarded-For": { - "hmac":true - } - } - } - ``` - -
-
- -# /sys/config/auditing/request-headers/ - -## GET - -
-
Description
-
- List the information for the given request header. _This endpoint requires `sudo` - capability._ -
- -
Method
-
GET
- -
URL
-
`/sys/config/auditing/request-headers/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "X-Forwarded-For": { - "hmac":true - } - } - ``` - -
-
- -## PUT - -
-
Description
-
- Enable auditing of a header. _This endpoint requires `sudo` capability._ -
- -
Method
-
PUT
- -
URL
-
`/sys/config/auditing/request-headers/`
- -
Parameters
-
-
    -
  • - hmac - optional - Bool, if this header's value should be hmac'ed in the audit logs. - Defaults to false. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Disable auditing of the given request header. _This endpoint requires `sudo` - capability._ -
- -
Method
-
DELETE
- -
URL
-
`/sys/config/auditing/request-headers/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-generate-root.html.md b/website/source/docs/http/sys-generate-root.html.md deleted file mode 100644 index 01a77b28c..000000000 --- a/website/source/docs/http/sys-generate-root.html.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/generate-root/" -sidebar_current: "docs-http-sys-generate-root" -description: |- - The `/sys/generate-root/` endpoints are used to create a new root key for Vault. ---- - -# /sys/generate-root/attempt - -## GET - -
-
Description
-
- Reads the configuration and progress of the current root generation - attempt. -
- -
Method
-
GET
- -
URL
-
`/sys/generate-root/attempt`
- -
Parameters
-
- None -
- -
Returns
-
- If a root generation is started, `progress` is how many unseal keys have - been provided for this generation attempt, where `required` must be reached - to complete. The `nonce` for the current attempt and whether the attempt is - complete is also displayed. If a PGP key is being used to encrypt the final - root token, its fingerprint will be returned. Note that if an OTP is being - used to encode the final root token, it will never be returned. - - ```javascript - { - "started": true, - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "progress": 1, - "required": 3, - "encoded_root_token": "", - "pgp_fingerprint": "", - "complete": false - } - ``` - -
-
- -## PUT - -
-
Description
-
- Initializes a new root generation attempt. Only a single root generation - attempt can take place at a time. One (and only one) of `otp` or `pgp_key` - are required. -
- -
Method
-
PUT
- -
URL
-
`/sys/generate-root/attempt`
- -
Parameters
-
-
    -
  • - otp - optional - A base64-encoded 16-byte value. The raw bytes of the token will be - XOR'd with this value before being returned to the final unseal key - provider. -
    • -
  • - pgp_key - optional - A base64-encoded PGP public key. The raw bytes of the token will be - encrypted with this value before being returned to the final unseal key - provider. -
    • -
-
- -
Returns
-
- The current progress. - - ```javascript - { - "started": true, - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "progress": 1, - "required": 3, - "encoded_root_token": "", - "pgp_fingerprint": "816938b8a29146fbe245dd29e7cbaf8e011db793", - "complete": false - } - ``` - -
-
- -## DELETE - -
-
Description
-
- Cancels any in-progress root generation attempt. This clears any progress - made. This must be called to change the OTP or PGP key being used. -
- -
Method
-
DELETE
- -
URL
-
`/sys/generate-root/attempt`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/generate-root/update - -## PUT - -
-
Description
-
- Enter a single master key share to progress the root generation attempt. - If the threshold number of master key shares is reached, Vault will - complete the root generation and issue the new token. Otherwise, this API - must be called multiple times until that threshold is met. The attempt - nonce must be provided with each call. -
- -
Method
-
PUT
- -
URL
-
`/sys/generate-root/update`
- -
Parameters
-
-
    -
  • - key - required - A single master share key. -
    • -
  • - nonce - required - The nonce of the attempt. -
    • -
-
- -
Returns
-
- A JSON-encoded object indicating the attempt nonce, and completion status, - and the encoded root token, if the attempt is complete. - - ```javascript - { - "started": true, - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "progress": 3, - "required": 3, - "pgp_fingerprint": "", - "complete": true, - "encoded_root_token": "FPzkNBvwNDeFh4SmGA8c+w==" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-health.html.md b/website/source/docs/http/sys-health.html.md deleted file mode 100644 index 7b1248751..000000000 --- a/website/source/docs/http/sys-health.html.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/health" -sidebar_current: "docs-http-debug-health" -description: |- - The '/sys/health' endpoint is used to check the health status of Vault. ---- - -# /sys/health - -
-
Description
-
- Returns the health status of Vault. This matches the semantics of a - Consul HTTP health check and provides a simple way to monitor the - health of a Vault instance. -
- -
Method
-
GET/HEAD
- -
Parameters
-
-
    -
  • - standbyok - optional - A query parameter provided to indicate that being a standby should - still return the active status code instead of the standby code -
    • -
  • - activecode - optional - A query parameter provided to indicate the status code that should - be returned for an active node instead of the default of `200` -
    • -
  • - standbycode - optional - A query parameter provided to indicate the status code that should - be returned for a standby node instead of the default of `429` -
    • -
  • - sealedcode - optional - A query parameter provided to indicate the status code that should - be returned for a sealed node instead of the default of `503` -
    • -
  • - uninitcode - optional - A query parameter provided to indicate the status code that should - be returned for an uninitialized Vault instead of the default of - `501` -
    • -
-
- -
Returns (only with GET)
-
- - ```javascript - { - "cluster_id": "c9abceea-4f46-4dab-a688-5ce55f89e228", - "cluster_name": "vault-cluster-5515c810", - "version": "0.6.1-dev" - "server_time_utc": 1469555798, - "standby": false, - "sealed": false, - "initialized": true - } - ``` - - Default Status Codes (GET/HEAD): - - * `200` if initialized, unsealed, and active. - * `429` if unsealed and standby. - * `501` if not initialized. - * `503` if sealed. -
-
diff --git a/website/source/docs/http/sys-init.html.md b/website/source/docs/http/sys-init.html.md deleted file mode 100644 index f403e02ad..000000000 --- a/website/source/docs/http/sys-init.html.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/init" -sidebar_current: "docs-http-sys-init" -description: |- - The '/sys/init' endpoint is used to initialize a new Vault. ---- - -# /sys/init - -## GET - -
-
Description
-
- Return the initialization status of a Vault. -
- -
Method
-
GET
- -
Parameters
-
None
- -
Returns
-
- - ```javascript - { - "initialized": true - } - ``` - -
-
- -## PUT - -
-
Description
-
- Initializes a new Vault. The Vault must not have been previously - initialized. The recovery options, as well as the stored shares option, are - only available when using Vault HSM. -
- -
Method
-
PUT
- -
Parameters
-
-
    -
  • - root_token_pgp_key - optional - A PGP public key used to encrypt the initial root token. The key - must be base64-encoded from its original binary representation. -
    • -
  • - secret_shares - required - The number of shares to split the master key into. -
    • -
  • - secret_threshold - required - The number of shares required to reconstruct the master key. This must - be less than or equal to secret_shares. If using Vault HSM - with auto-unsealing, this value must be the same as - secret_shares. -
    • -
  • - pgp_keys - optional - An array of PGP public keys used to encrypt the output unseal keys. - Ordering is preserved. The keys must be base64-encoded from their - original binary representation. The size of this array must be the - same as secret_shares. -
    • -
  • - stored_shares - required - The number of shares that should be encrypted by the HSM and stored for - auto-unsealing (Vault HSM only). Currently must be the same as - secret_shares. -
    • -
  • - recovery_shares - required - The number of shares to split the recovery key into (Vault HSM only). -
    • -
  • - recovery_threshold - required - The number of shares required to reconstruct the recovery key (Vault - HSM only). This must be less than or equal to - recovery_shares. -
    • -
  • - recovery_pgp_keys - optional - An array of PGP public keys used to encrypt the output recovery keys - (Vault HSM only). Ordering is preserved. The keys must be - base64-encoded from their original binary representation. The size of - this array must be the same as recovery_shares. -
    • -
-
- -
Returns
-
- A JSON-encoded object including the (possibly encrypted, if - pgp_keys was provided) master keys, base 64 encoded master keys and initial root token: - - ```javascript - { - "keys": ["one", "two", "three"], - "keys_base64": ["cR9No5cBC", "F3VLrkOo", "zIDSZNGv"], - "root_token": "foo" - } - ``` - -
- -
See Also
-
- For more information on the PGP/Keybase.io process please see the - [Vault GPG and Keybase integration documentation](/docs/concepts/pgp-gpg-keybase.html). -
-
diff --git a/website/source/docs/http/sys-key-status.html.md b/website/source/docs/http/sys-key-status.html.md deleted file mode 100644 index 74d3ffde2..000000000 --- a/website/source/docs/http/sys-key-status.html.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/key-status" -sidebar_current: "docs-http-rotate-key-status" -description: |- - The '/sys/key-status' endpoint is used to query info about the current encryption key of Vault. ---- - -# /sys/key-status - -
-
Description
-
- Returns information about the current encryption key used by Vault. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- The "term" parameter is the sequential key number, and "install_time" is the time that - encryption key was installed. - - ```javascript - { - "term": 3, - "install_time": "2015-05-29T14:50:46.223692553-07:00" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-leader.html.md b/website/source/docs/http/sys-leader.html.md deleted file mode 100644 index 273ac3102..000000000 --- a/website/source/docs/http/sys-leader.html.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/leader" -sidebar_current: "docs-http-ha-leader" -description: |- - The '/sys/leader' endpoint is used to check the high availability status and current leader of Vault. ---- - -# /sys/leader - -
-
Description
-
- Returns the high availability status and current leader instance of Vault. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "ha_enabled": true, - "is_self": false, - "leader_address": "https://127.0.0.1:8200/" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-mounts.html.md b/website/source/docs/http/sys-mounts.html.md deleted file mode 100644 index 489c672ba..000000000 --- a/website/source/docs/http/sys-mounts.html.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/mounts" -sidebar_current: "docs-http-mounts-mounts" -description: |- - The '/sys/mounts' endpoint is used manage secret backends in Vault. ---- - -# /sys/mounts - -## GET - -
-
Description
-
- Lists all the mounted secret backends. `default_lease_ttl` - or `max_lease_ttl` values of `0` mean that the system - defaults are used by this backend. -
- -
Method
-
GET
- -
URL
-
`/sys/mounts`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "aws": { - "type": "aws", - "description": "AWS keys", - "config": { - "default_lease_ttl": 0, - "max_lease_ttl": 0, - "force_no_cache": false - } - }, - - "sys": { - "type": "system", - "description": "system endpoint", - "config": { - "default_lease_ttl": 0, - "max_lease_ttl": 0, - "force_no_cache": false - } - } - } - ``` - -
-
- -## POST - -
-
Description
-
- Mount a new secret backend to the mount point in the URL. -
- -
Method
-
POST
- -
URL
-
`/sys/mounts/`
- -
Parameters
-
-
    -
  • - type - required - The name of the backend type, such as "aws" -
    • -
  • - description - optional - A human-friendly description of the mount. -
    • -
  • - config - optional - Config options for this mount. This is an object with - three possible values: `default_lease_ttl`, - `max_lease_ttl`, and`force_no_cache`. These control the default and - maximum lease time-to-live, and force disabling backend caching respectively. - If set on a specific mount, this overrides the global defaults. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Unmount the mount point specified in the URL. -
- -
Method
-
DELETE
- -
URL
-
`/sys/mounts/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/mounts/[mount point]/tune - -## GET - -
-
Description
-
- Read the given mount's configuration. Unlike the `mounts` - endpoint, this will return the current time in seconds for each - TTL, which may be the system default or a mount-specific value. -
- -
Method
-
GET
- -
URL
-
`/sys/mounts//tune`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "default_lease_ttl": 3600, - "max_lease_ttl": 7200, - "force_no_cache": false - } - ``` - -
-
- -## POST - -
-
Description
-
- Tune configuration parameters for a given mount point. -
- -
Method
-
POST
- -
URL
-
`/sys/mounts//tune`
- -
Parameters
-
-
    -
  • - default_lease_ttl - optional - The default time-to-live. If set on a specific mount, - overrides the global default. A value of "system" or "0" - are equivalent and set to the system default TTL. -
    • -
  • - max_lease_ttl - optional - The maximum time-to-live. If set on a specific mount, - overrides the global default. A value of "system" or "0" - are equivalent and set to the system max TTL. -
    • -
-
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-policy.html.md b/website/source/docs/http/sys-policy.html.md deleted file mode 100644 index 22eb920bc..000000000 --- a/website/source/docs/http/sys-policy.html.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/policy" -sidebar_current: "docs-http-auth-policy" -description: |- - The `/sys/policy` endpoint is used to manage ACL policies in Vault. ---- - -# /sys/policy - -## GET - -
-
Description
-
- Lists all the available policies. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "policies": ["root", "deploy"] - } - ``` - -
-
- -# /sys/policy/ - -## GET - -
-
Description
-
- Retrieve the rules for the named policy. -
- -
Method
-
GET
- -
URL
-
`/sys/policy/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "rules": "path..." - } - ``` - -
-
- - -## PUT - -
-
Description
-
- Add or update a policy. Once a policy is updated, it takes effect - immediately to all associated users. -
- -
Method
-
PUT
- -
URL
-
`/sys/policy/`
- -
Parameters
-
-
    -
  • - rules - required - The policy document. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Delete the policy with the given name. This will immediately - affect all associated users. -
- -
Method
-
DELETE
- -
URL
-
`/sys/policy/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-raw.html.md b/website/source/docs/http/sys-raw.html.md deleted file mode 100644 index 2ce1a206f..000000000 --- a/website/source/docs/http/sys-raw.html.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/raw" -sidebar_current: "docs-http-debug-raw" -description: |- - The `/sys/raw` endpoint is access the raw underlying store in Vault. ---- - -# /sys/raw - -## GET - -
-
Description
-
- Reads the value of the key at the given path. This is the raw path in the - storage backend and not the logical path that is exposed via the mount system. -
- -
Method
-
GET
- -
URL
-
`/sys/raw/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "value": "{'foo':'bar'}" - } - ``` - -
-
- -## PUT - -
-
Description
-
- Update the value of the key at the given path. This is the raw path in the - storage backend and not the logical path that is exposed via the mount system. -
- -
Method
-
PUT
- -
URL
-
`/sys/raw/`
- -
Parameters
-
-
    -
  • - value - required - The value of the key. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Delete the key with given path. This is the raw path in the - storage backend and not the logical path that is exposed via the mount system. -
- -
Method
-
DELETE
- -
URL
-
`/sys/raw/`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-rekey.html.md b/website/source/docs/http/sys-rekey.html.md deleted file mode 100644 index 70260ac7a..000000000 --- a/website/source/docs/http/sys-rekey.html.md +++ /dev/null @@ -1,251 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/rekey/" -sidebar_current: "docs-http-rotate-rekey" -description: |- - The `/sys/rekey/` endpoints are used to rekey the unseal keys for Vault. ---- - -# /sys/rekey/init - -## GET - -
-
Description
-
- Reads the configuration and progress of the current rekey attempt. -
- -
Method
-
GET
- -
URL
-
`/sys/rekey/init`
- -
Parameters
-
- None -
- -
Returns
-
- If a rekey is started, then `n` is the new shares to generate and `t` is - the threshold required for the new shares. `progress` is how many unseal - keys have been provided for this rekey, where `required` must be reached to - complete. The `nonce` for the current rekey operation is also displayed. If - PGP keys are being used to encrypt the final shares, the key fingerprints - and whether the final keys will be backed up to physical storage will also - be displayed. - - ```javascript - { - "started": true, - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "t": 3, - "n": 5, - "progress": 1, - "required": 3, - "pgp_fingerprints": ["abcd1234"], - "backup": true - } - ``` - -
-
- -## PUT - -
-
Description
-
- Initializes a new rekey attempt. Only a single rekey attempt can take place - at a time, and changing the parameters of a rekey requires canceling and - starting a new rekey, which will also provide a new nonce. -
- -
Method
-
PUT
- -
URL
-
`/sys/rekey/init`
- -
Parameters
-
-
    -
  • - secret_shares - required - The number of shares to split the master key into. -
    • -
  • - secret_threshold - required - The number of shares required to reconstruct the master key. - This must be less than or equal to secret_shares. -
    • -
  • - pgp_keys - optional - An array of PGP public keys used to encrypt the output unseal keys. - Ordering is preserved. The keys must be base64-encoded from their - original binary representation. The size of this array must be the - same as secret_shares. -
    • -
  • - backup - optional - If using PGP-encrypted keys, whether Vault should also back them up to - a well-known location in physical storage (`core/unseal-keys-backup`). - These can then be retrieved and removed via the `sys/rekey/backup` - endpoint. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -## DELETE - -
-
Description
-
- Cancels any in-progress rekey. This clears the rekey settings as well as any - progress made. This must be called to change the parameters of the rekey. -
- -
Method
-
DELETE
- -
URL
-
`/sys/rekey/init`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/rekey/backup - -## GET - -
-
Description
-
- Return the backup copy of PGP-encrypted unseal keys. The returned value is - the nonce of the rekey operation and a map of PGP key fingerprint to - hex-encoded PGP-encrypted key. -
- -
Method
-
GET
- -
URL
-
`/sys/rekey/backup`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "keys": { - "abcd1234": "..." - } - } - ``` - -
-
- -## DELETE - -
-
Description
-
- Delete the backup copy of PGP-encrypted unseal keys. -
- -
Method
-
DELETE
- -
URL
-
`/sys/rekey/backup`
- -
Parameters
-
None -
- -
Returns
-
`204` response code. -
-
- -# /sys/rekey/update - -## PUT - -
-
Description
-
- Enter a single master key share to progress the rekey of the Vault. - If the threshold number of master key shares is reached, Vault - will complete the rekey. Otherwise, this API must be called multiple - times until that threshold is met. The rekey nonce operation must be - provided with each call. -
- -
Method
-
PUT
- -
URL
-
`/sys/rekey/update`
- -
Parameters
-
-
    -
  • - key - required - A single master share key. -
    • -
  • - nonce - required - The nonce of the rekey operation. -
    • -
-
- -
Returns
-
- A JSON-encoded object indicating the rekey operation nonce and completion - status; if completed, the new master keys are returned. If the keys are - PGP-encrypted, an array of key fingerprints will also be provided (with the - order in which the keys were used for encryption) along with whether or not - the keys were backed up to physical storage: - - ```javascript - { - "complete": true, - "keys": ["one", "two", "three"], - "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", - "pgp_fingerprints": ["abcd1234"], - "keys_base64": ["base64keyvalue"], - "backup": true - } - ``` - -
-
diff --git a/website/source/docs/http/sys-remount.html.md b/website/source/docs/http/sys-remount.html.md deleted file mode 100644 index 231e77092..000000000 --- a/website/source/docs/http/sys-remount.html.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/remount" -sidebar_current: "docs-http-mounts-remount" -description: |- - The '/sys/remount' endpoint is used remount a mounted backend to a new endpoint. ---- - -# /sys/remount - -
-
Description
-
- Remount an already-mounted backend to a new mount point. -
- -
Method
-
POST
- -
Parameters
-
-
    -
  • - from - required - The previous mount point. -
    • -
  • - to - required - The new mount point. -
    • -
-
- -
Returns
-
`204` response code. -
-
diff --git a/website/source/docs/http/sys-renew.html.md b/website/source/docs/http/sys-renew.html.md deleted file mode 100644 index fdfbc62bd..000000000 --- a/website/source/docs/http/sys-renew.html.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/renew" -sidebar_current: "docs-http-lease-renew" -description: |- - The `/sys/renew` endpoint is used to renew secrets. ---- - -# /sys/renew - -
-
Description
-
- Renew a secret, requesting to extend the lease. -
- -
Method
-
PUT
- -
URL
-
`/sys/renew(/)`
- -
Parameters
-
-
    -
  • - increment - optional - A requested amount of time in seconds to extend the lease. - This is advisory. -
    • -
  • - lease_id - required - The ID of the lease to extend. This can be specified as part of the URL - or in the request body. -
    • -
-
- -
Returns
-
A secret structure. -
-
diff --git a/website/source/docs/http/sys-revoke-force.html.md b/website/source/docs/http/sys-revoke-force.html.md deleted file mode 100644 index 9f30b1511..000000000 --- a/website/source/docs/http/sys-revoke-force.html.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/revoke-force" -sidebar_current: "docs-http-lease-revoke-force" -description: |- - The `/sys/revoke-force` endpoint is used to revoke secrets or tokens based on prefix while ignoring backend errors. ---- - -# /sys/revoke-force - -
-
Description
-
- Revoke all secrets or tokens generated under a given prefix immediately. - Unlike `/sys/revoke-prefix`, this path ignores backend errors encountered - during revocation. This is potentially very dangerous and should - only be used in specific emergency situations where errors in the backend - or the connected backend service prevent normal revocation. By ignoring - these errors, Vault abdicates responsibility for ensuring that the issued - credentials or secrets are properly revoked and/or cleaned up. Access to - this endpoint should be tightly controlled. -
- -
Method
-
PUT
- -
URL
-
`/sys/revoke-force/`
- -
Parameters
-
None
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-revoke-prefix.html.md b/website/source/docs/http/sys-revoke-prefix.html.md deleted file mode 100644 index 606758aab..000000000 --- a/website/source/docs/http/sys-revoke-prefix.html.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/revoke-prefix" -sidebar_current: "docs-http-lease-revoke-prefix" -description: |- - The `/sys/revoke-prefix` endpoint is used to revoke secrets or tokens based on prefix. ---- - -# /sys/revoke-prefix - -
-
Description
-
- Revoke all secrets (via a lease ID prefix) or tokens (via the tokens' path - property) generated under a given prefix immediately. This requires `sudo` - capability and access to it should be tightly controlled as it can be used - to revoke very large numbers of secrets/tokens at once. -
- -
Method
-
PUT
- -
URL
-
`/sys/revoke-prefix/`
- -
Parameters
-
None
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-revoke.html.md b/website/source/docs/http/sys-revoke.html.md deleted file mode 100644 index 04672c75d..000000000 --- a/website/source/docs/http/sys-revoke.html.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/revoke" -sidebar_current: "docs-http-lease-revoke-single" -description: |- - The `/sys/revoke` endpoint is used to revoke secrets. ---- - -# /sys/revoke - -
-
Description
-
- Revoke a secret immediately. -
- -
Method
-
PUT
- -
URL
-
`/sys/revoke/`
- -
Parameters
-
None
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-rotate.html.md b/website/source/docs/http/sys-rotate.html.md deleted file mode 100644 index 7b5b07044..000000000 --- a/website/source/docs/http/sys-rotate.html.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/rotate" -sidebar_current: "docs-http-rotate-rotate" -description: |- - The `/sys/rotate` endpoint is used to rotate the encryption key. ---- - -# /sys/rotate - -## PUT - -
-
Description
-
- Trigger a rotation of the backend encryption key. This is the key that is used - to encrypt data written to the storage backend, and is not provided to operators. - This operation is done online. Future values are encrypted with the new key, while - old values are decrypted with previous encryption keys. -
- -
Method
-
PUT
- -
URL
-
`/sys/rotate`
- -
Parameters
-
- None -
- -
Returns
-
`204` response code. -
-
- diff --git a/website/source/docs/http/sys-seal-status.html.md b/website/source/docs/http/sys-seal-status.html.md deleted file mode 100644 index f6fdc4758..000000000 --- a/website/source/docs/http/sys-seal-status.html.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/seal-status" -sidebar_current: "docs-http-seal-status" -description: |- - The '/sys/seal-status' endpoint is used to check the seal status of a Vault. ---- - -# /sys/seal-status - -
-
Description
-
- Returns the seal status of the Vault.

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- The "t" parameter is the threshold, and "n" is the number of shares. - - ```javascript - { - "sealed": true, - "t": 3, - "n": 5, - "progress": 2, - "version": "0.6.1-dev" - } - ``` - - Sample response when Vault is unsealed. - - ```javascript - { - "sealed": false, - "t": 3, - "n": 5, - "progress": 0, - "version": "0.6.1-dev", - "cluster_name": "vault-cluster-d6ec3c7f", - "cluster_id": "3e8b3fec-3749-e056-ba41-b62a63b997e8" - } - ``` - -
-
diff --git a/website/source/docs/http/sys-seal.html.md b/website/source/docs/http/sys-seal.html.md deleted file mode 100644 index d82b9af38..000000000 --- a/website/source/docs/http/sys-seal.html.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/seal" -sidebar_current: "docs-http-seal-seal" -description: |- - The '/sys/seal' endpoint seals the Vault. ---- - -# /sys/seal - -
-
Description
-
- Seals the Vault. In HA mode, only an active node can be sealed. Standby - nodes should be restarted to get the same effect. Requires a token with - `root` policy or `sudo` capability on the path. -
- -
Method
-
PUT
- -
Parameters
-
- None -
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-step-down.html.md b/website/source/docs/http/sys-step-down.html.md deleted file mode 100644 index 6e2f26617..000000000 --- a/website/source/docs/http/sys-step-down.html.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/step-down" -sidebar_current: "docs-http-ha-step-down" -description: |- - The '/sys/step-down' endpoint causes the node to give up active status. ---- - -# /sys/step-down - -
-
Description
-
- Forces the node to give up active status. If the node does not have active - status, this endpoint does nothing. Note that the node will sleep for ten - seconds before attempting to grab the active lock again, but if no standby - nodes grab the active lock in the interim, the same node may become the - active node again. Requires a token with `root` policy or `sudo` capability - on the path. -
- -
Method
-
PUT
- -
Parameters
-
- None -
- -
Returns
-
A `204` response code. -
-
diff --git a/website/source/docs/http/sys-unseal.html.md b/website/source/docs/http/sys-unseal.html.md deleted file mode 100644 index 94f21a644..000000000 --- a/website/source/docs/http/sys-unseal.html.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/seal-unseal" -sidebar_current: "docs-http-seal-unseal" -description: |- - The '/sys/seal-unseal' endpoint is used to unseal the Vault. ---- - -# /sys/unseal - -
-
Description
-
- Enter a single master key share to progress the unsealing of the Vault. - If the threshold number of master key shares is reached, Vault - will attempt to unseal the Vault. Otherwise, this API must be - called multiple times until that threshold is met.

Either - the `key` or `reset` parameter must be provided; if both are provided, - `reset` takes precedence. -
- -
Method
-
PUT
- -
Parameters
-
-
    -
  • - key - optional - A single master share key. -
    • -
  • - reset - optional - A boolean; if true, the previously-provided unseal keys are discarded - from memory and the unseal process is reset. -
    • -
-
-
Returns
-
The same result as `/sys/seal-status`. -
-
diff --git a/website/source/docs/http/sys-wrapping-lookup.html.md b/website/source/docs/http/sys-wrapping-lookup.html.md deleted file mode 100644 index c2d1d66b9..000000000 --- a/website/source/docs/http/sys-wrapping-lookup.html.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/wrapping/lookup" -sidebar_current: "docs-http-wrapping-lookup" -description: |- - The '/sys/wrapping/lookup' endpoint returns wrapping token properties ---- - -# /sys/wrapping/lookup - -## POST - -
-
Description
-
- Looks up wrapping properties for the given token. -
- -
Method
-
POST
- -
URL
-
`/sys/wrapping/lookup`
- -
Parameters
-
-
    -
  • - token - required - The wrapping token ID. -
    • -
-
- -
Returns
-
- - ```javascript - { - "request_id": "481320f5-fdf8-885d-8050-65fa767fd19b", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "creation_time": "2016-09-28T14:16:13.07103516-04:00", - "creation_ttl": 300 - }, - "warnings": null - } - ``` - -
-
diff --git a/website/source/docs/http/sys-wrapping-rewrap.html.md b/website/source/docs/http/sys-wrapping-rewrap.html.md deleted file mode 100644 index 5fd3fc79b..000000000 --- a/website/source/docs/http/sys-wrapping-rewrap.html.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/wrapping/rewrap" -sidebar_current: "docs-http-wrapping-rewrap" -description: |- - The '/sys/wrapping/rewrap' endpoint can be used to rotate a wrapping token and refresh its TTL ---- - -# /sys/wrapping/rewrap - -## POST - -
-
Description
-
- Rewraps a response-wrapped token; the new token will use the same creation - TTL as the original token and contain the same response. The old token will - be invalidated. This can be used for long-term storage of a secret in a - response-wrapped token when rotation is a requirement. -
- -
Method
-
POST
- -
URL
-
`/sys/wrapping/rewrap`
- -
Parameters
-
-
    -
  • - token - required - The wrapping token ID. -
    • -
-
- -
Returns
-
- - ```javascript - { - "request_id": "", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": null, - "warnings": null, - "wrap_info": { - "token": "3b6f1193-0707-ac17-284d-e41032e74d1f", - "ttl": 300, - "creation_time": "2016-09-28T14:22:26.486186607-04:00", - "wrapped_accessor": "" - } - } - ``` - -
-
diff --git a/website/source/docs/http/sys-wrapping-unwrap.html.md b/website/source/docs/http/sys-wrapping-unwrap.html.md deleted file mode 100644 index 3532117e9..000000000 --- a/website/source/docs/http/sys-wrapping-unwrap.html.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/wrapping/unwrap" -sidebar_current: "docs-http-wrapping-unwrap" -description: |- - The '/sys/wrapping/unwrap' endpoint unwraps a wrapped response ---- - -# /sys/wrapping/unwrap - -## POST - -
-
Description
-
- Returns the original response inside the given wrapping token. Unlike - simply reading `cubbyhole/response` (which is deprecated), this endpoint - provides additional validation checks on the token, returns the original - value on the wire rather than a JSON string representation of it, and - ensures that the response is properly audit-logged.

This endpoint - can be used by using a wrapping token as the client token in the API call, - in which case the `token` parameter is not required; or, a different token - with permissions to access this endpoint can make the call and pass in the - wrapping token in the `token` parameter. Do _not_ use the wrapping token in - both locations; this will cause the wrapping token to be revoked but the - value to be unable to be looked up, as it will basically be a double-use of - the token! -
- -
Method
-
POST
- -
URL
-
`/sys/wrapping/unwrap`
- -
Parameters
-
-
    -
  • - token - optional - The wrapping token ID; required if the client token is not the wrapping - token. Do not use the wrapping token in both locations. -
    • -
-
- -
Returns
-
- - ```javascript - { - "request_id": "8e33c808-f86c-cff8-f30a-fbb3ac22c4a8", - "lease_id": "", - "lease_duration": 2592000, - "renewable": false, - "data": { - "zip": "zap" - }, - "warnings": null - } - ``` - -
-
diff --git a/website/source/docs/http/sys-wrapping-wrap.html.md b/website/source/docs/http/sys-wrapping-wrap.html.md deleted file mode 100644 index ce69c57a3..000000000 --- a/website/source/docs/http/sys-wrapping-wrap.html.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/wrapping/wrap" -sidebar_current: "docs-http-wrapping-wrap" -description: |- - The '/sys/wrapping/wrap' endpoint wraps the given values in a response-wrapped token ---- - -# /sys/wrapping/wrap - -## POST - -
-
Description
-
- Wraps the given user-supplied data inside a response-wrapped token. -
- -
Method
-
POST
- -
URL
-
`/sys/wrapping/wrap`
- -
Parameters
-
-
    -
  • - [any] - optional - Parameters should be supplied as keys/values in a JSON object. The - exact set of given parameters will be contained in the wrapped - response. -
    • -
-
- -
Returns
-
- - ```javascript - { - "request_id": "", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": null, - "warnings": null, - "wrap_info": { - "token": "fb79b9d3-d94e-9eb6-4919-c559311133d6", - "ttl": 300, - "creation_time": "2016-09-28T14:41:00.56961496-04:00", - "wrapped_accessor": "" - } - } - ``` - -
-
diff --git a/website/source/docs/http/system/audit-hash.html.md b/website/source/docs/http/system/audit-hash.html.md new file mode 100644 index 000000000..add41dd74 --- /dev/null +++ b/website/source/docs/http/system/audit-hash.html.md @@ -0,0 +1,63 @@ +--- +layout: "http" +page_title: /sys/audit-hash - HTTP API" +sidebar_current: "docs-http-system-audit-hash" +description: |- + The `/sys/audit-hash` endpoint is used to hash data using an audit backend's + hash function and salt. +--- + +# `/sys/audit-hash` + +The `/sys/audit-hash` endpoint is used to calculate the hash of the data used by +an audit backend's hash function and salt. This can be used to search audit logs +for a hashed value when the original value is known. + +## Calculate Hash + +This endpoint hashes the given input data with the specified audit backend's +hash function and salt. This endpoint can be used to discover whether a given +plaintext string (the `input` parameter) appears in the audit log in obfuscated +form. + +The audit log records requests and responses. Since the Vault API is JSON-based, +any binary data returned from an API call (such as a DER-format certificate) is +base64-encoded by the Vault server in the response. As a result such information +should also be base64-encoded to supply into the `input` parameter. + +| Method | Path | Produces | +| :------- | :---------------------- | :--------------------- | +| `POST` | `/sys/audit-hash/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the audit backend to + generate hashes for. This is part of the request URL. + +- `input` `(string: )` – Specifies the input string to hash. + +### Sample Payload + +```json +{ + "input": "my-secret-vault" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/audit-hash/example-audit +``` + +### Sample Response + +```json +{ + "hash": "hmac-sha256:08ba35..." +} +``` diff --git a/website/source/docs/http/system/audit.html.md b/website/source/docs/http/system/audit.html.md new file mode 100644 index 000000000..f1720e525 --- /dev/null +++ b/website/source/docs/http/system/audit.html.md @@ -0,0 +1,118 @@ +--- +layout: "http" +page_title: "/sys/audit - HTTP API" +sidebar_current: "docs-http-system-audit/" +description: |- + The `/sys/audit` endpoint is used to enable and disable audit backends. +--- + +# `/sys/audit` + +The `/sys/audit` endpoint is used to list, mount, and unmount audit backends. +Audit backends must be enabled before use, and more than one backend may be +enabled at a time. + +## List Mounted Audit Backends + +This endpoint lists only the mounted audit backends (it does not list all +available audit backends). + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/audit` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/audit +``` + +### Sample Response + +```javascript +{ + "file": { + "type": "file", + "description": "Store logs in a file", + "options": { + "path": "/var/log/vault.log" + } + } +} +``` + +## Mount Audit Backend + +This endpoint mounts a new audit backend at the supplied path. The path can be a +single word name or a more complex, nested path. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/audit/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path in which to mount the audit + backend. This is part of the request URL. + +- `description` `(string: "")` – Specifies a human-friendly description of the + audit backend. + +- `options` `(map: nil)` – Specifies configuration options to + pass to the audit backend itself. This is dependent on the audit backend type. + +- `type` `(string: )` – Specifies the type of the audit backend. + +### Sample Payload + +```json +{ + "type": "file", + "options": { + "path": "/var/log/vault/log" + } +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/audit/example-audit +``` + +## Unmount Audit Backend + +This endpoint un-mounts the audit backend at the given path. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/audit/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the audit backend to + delete. This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/audit/example-audit +``` diff --git a/website/source/docs/http/system/auth.html.md b/website/source/docs/http/system/auth.html.md new file mode 100644 index 000000000..52ab68f6b --- /dev/null +++ b/website/source/docs/http/system/auth.html.md @@ -0,0 +1,193 @@ +--- +layout: "http" +page_title: "/sys/auth - HTTP API" +sidebar_current: "docs-http-system-auth" +description: |- + The `/sys/auth` endpoint is used to manage auth backends in Vault. +--- + +# `/sys/auth` + +The `/sys/auth` endpoint is used to list, create, update, and delete auth +backends. Auth backends convert user or machine-supplied information into a +token which can be used for all future requests. + +## List Auth Backends + +This endpoint lists all enabled auth backends. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/auth` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/auth +``` + +### Sample Response + +```json +{ + "github/": { + "type": "github", + "description": "GitHub auth" + }, + "token/": { + "config": { + "default_lease_ttl": 0, + "max_lease_ttl": 0 + }, + "description": "token based credentials", + "type": "token" + } +} +``` + +## Mount Auth Backend + +This endpoint enables a new auth backend. After mounting, the auth backend can +be accessed and configured via the auth path specified as part of the URL. This +auth path will be nested under the `auth` prefix. + +For example, mounting the "foo" auth backend will make it accessible at +`/auth/foo`. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/auth/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path in which to mount the auth + backend. This is part of the request URL. + +- `description` `(string: "")` – Specifies a human-friendly description of the + auth backend. + +- `type` `(string: )` – Specifies the name of the authentication + backend type, such as "github" or "token". + +### Sample Payload + +```json +{ + "type": "github", + "description": "Login with GitHub" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/auth/my-auth +``` + +## Unmount Auth Backend + +This endpoint un-mounts the auth backend at the given auth path. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/auth/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path to unmount. This is part of + the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/auth/my-auth +``` + +## Read Auth Backend Tuning + +This endpoint reads the given auth path's configuration. _This endpoint requires +`sudo` capability on the final path, but the same functionality can be achieved +without `sudo` via `sys/mounts/auth/[auth-path]/tune`._ + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/auth/:path/tune` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path in which to tune. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/auth/my-auth/tune +``` + +### Sample Response + +```json +{ + "default_lease_ttl": 3600, + "max_lease_ttl": 7200 +} +``` + +## Tune Auth Backend + +Tune configuration parameters for a given auth path. _This endpoint +requires `sudo` capability on the final path, but the same functionality +can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._ + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/auth/:path/tune` | `204 (empty body)` | + +### Parameters + +- `default_lease_ttl` `(int: 0)` – Specifies the default time-to-live. If set on + a specific auth path, this overrides the global default. + +- `max_lease_ttl` `(int: 0)` – Specifies the maximum time-to-live. If set on a + specific auth path, this overrides the global default. + +### Sample Payload + +```json +{ + "default_lease_ttl": 1800, + "max_lease_ttl": 86400 +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/auth/my-auth/tune +``` diff --git a/website/source/docs/http/system/capabilities-accessor.html.md b/website/source/docs/http/system/capabilities-accessor.html.md new file mode 100644 index 000000000..02f929908 --- /dev/null +++ b/website/source/docs/http/system/capabilities-accessor.html.md @@ -0,0 +1,57 @@ +--- +layout: "http" +page_title: "/sys/capabilities-accessor - HTTP API" +sidebar_current: "docs-http-system-capabilities-accessor" +description: |- + The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of + the token associated with an accessor, on the given path. +--- + +# `/sys/capabilities-accessor` + +The `/sys/capabilities-accessor` endpoint is used to fetch the capabilities of a +token associated with an accessor. + +## Query Token Accessor Capabilities + +This endpoint returns the capabilities of the token associated with an accessor, +for the given path. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/capabilities-accessor` | `200 application/json` | + +### Parameters + +- `accessor` `(string: )` – Specifies the accessor of the token to + check. + +- `path` `(string: )` – Specifies the path on which the token's + capabilities will be checked. + +### Sample Payload + +```json +{ + "accessor": "abcd1234", + "path": "secret/foo" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data payload.json \ + https://vault.rocks/v1/sys/capabilities-accessor +``` + +### Sample Response + +```json +{ + "capabilities": ["read", "list"] +} +``` diff --git a/website/source/docs/http/system/capabilities-self.html.md b/website/source/docs/http/system/capabilities-self.html.md new file mode 100644 index 000000000..259928fc3 --- /dev/null +++ b/website/source/docs/http/system/capabilities-self.html.md @@ -0,0 +1,54 @@ +--- +layout: "http" +page_title: "/sys/capabilities-self - HTTP API" +sidebar_current: "docs-http-system-capabilities-self" +description: |- + The `/sys/capabilities-self` endpoint is used to fetch the capabilities of + client token on a given path. +--- + +# `/sys/capabilities-self` + +The `/sys/capabilities-self` endpoint is used to fetch the capabilities of a the +supplied token. + +## Query Self Capabilities + +This endpoint returns the capabilities of client token on the given path. The +client token is the Vault token with which this API call is made. + +| Method | Path | Produces | +| :------- | :----------------------- | :--------------------- | +| `POST` | `/sys/capabilities-self` | `200 application/json` | + + +### Parameters + +- `path` `(string: )` – Specifies the path on which the client token's + capabilities will be checked. + +### Sample Payload + +```json +{ + "path": "secret/foo" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data payload.json \ + https://vault.rocks/v1/sys/capabilities-self +``` + +### Sample Response + +```json +{ + "capabilities": ["read", "list"] +} +``` diff --git a/website/source/docs/http/system/capabilities.html.md b/website/source/docs/http/system/capabilities.html.md new file mode 100644 index 000000000..3faf9ebb8 --- /dev/null +++ b/website/source/docs/http/system/capabilities.html.md @@ -0,0 +1,56 @@ +--- +layout: "http" +page_title: "/sys/capabilities - HTTP API" +sidebar_current: "docs-http-system-capabilities/" +description: |- + The `/sys/capabilities` endpoint is used to fetch the capabilities of a token + on a given path. +--- + +# `/sys/capabilities` + +The `/sys/capabilities` endpoint is used to fetch the capabilities of a token on +a given path. + +## Query Token Capabilities + +This endpoint returns the list of capabilities for a provided token. + +| Method | Path | Produces | +| :------- | :------------------- | :--------------------- | +| `POST` | `/sys/capabilities` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path against which to check the + token's capabilities. + +- `token` `(string: )` – Specifies the token for which to check + capabilities. + +### Sample Payload + +```json +{ + "path": "secret/foo", + "token": "abcd1234" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/capabilities +``` + +### Sample Response + +```json +{ + "capabilities": ["read", "list"] +} +``` diff --git a/website/source/docs/http/system/config-auditing.html.md b/website/source/docs/http/system/config-auditing.html.md new file mode 100644 index 000000000..22c4bf691 --- /dev/null +++ b/website/source/docs/http/system/config-auditing.html.md @@ -0,0 +1,130 @@ +--- +layout: "http" +page_title: "/sys/config/auditing - HTTP API" +sidebar_current: "docs-http-system-config-auditing" +description: |- + The `/sys/config/auditing` endpoint is used to configure auditing settings. +--- + +# `/sys/config/auditing/request-headers` + +The `/sys/config/auditing` endpoint is used to configure auditing settings. + +## Read All Audited Request Headers + +This endpoint lists the request headers that are configured to be audited. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/config/auditing/request-headers` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/config/auditing/request-headers +``` + +### Sample Response + +```json +{ + "headers": { + "X-Forwarded-For": { + "hmac": true + } + } +} +``` + +## Read Single Audit Request Header + +This endpoint lists the information for the given request header. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/config/auditing/request-headers/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the request header to + query. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/config/auditing/request-headers/my-header +``` + +### Sample Response + +```json +{ + "X-Forwarded-For": { + "hmac": true + } +} +``` + +## Create/Update Audit Request Header + +This endpoint enables auditing of a header. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/config/auditing/request-headers/:name` | `204 (empty body)` | + +### Parameters + +- `hmac` `(bool: false)` – Specifies if this header's value should be HMAC'ed in + the audit logs. + +### Sample Payload + +```json +{ + "hmac": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data payload.json \ + https://vault.rocks/v1/sys/config/auditing/request-headers/my-header +``` + +## Delete Audit Request Header + +This endpoint disables auditing of the given request header. + +- **`sudo` required** – This endpoint requires `sudo` capability in addition to + any path-specific capabilities. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/config/auditing/request-headers/:name` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/config/auditing/request-headers/my-header +``` diff --git a/website/source/docs/http/system/generate-root.html.md b/website/source/docs/http/system/generate-root.html.md new file mode 100644 index 000000000..2deacc504 --- /dev/null +++ b/website/source/docs/http/system/generate-root.html.md @@ -0,0 +1,170 @@ +--- +layout: "http" +page_title: "/sys/generate-root - HTTP API" +sidebar_current: "docs-http-system-generate-root" +description: |- + The `/sys/generate-root/` endpoints are used to create a new root key for + Vault. +--- + +# `/sys/generate-root` + +The `/sys/generate-root` endpoint is used to create a new root key for Vault. + +## Read Root Generation Progress + +This endpoint reads the configuration and process of the current root generation +attempt. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/generate-root/attempt` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + https://vault.rocks/v1/sys/generate-root/attempt +``` + +### Sample Response + +```json +{ + "started": true, + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "progress": 1, + "required": 3, + "encoded_root_token": "", + "pgp_fingerprint": "", + "complete": false +} +``` + +If a root generation is started, `progress` is how many unseal keys have been +provided for this generation attempt, where `required` must be reached to +complete. The `nonce` for the current attempt and whether the attempt is +complete is also displayed. If a PGP key is being used to encrypt the final root +token, its fingerprint will be returned. Note that if an OTP is being used to +encode the final root token, it will never be returned. + +## Start Root Token Generation + +This endpoint initializes a new root generation attempt. Only a single root +generation attempt can take place at a time. One (and only one) of `otp` or +`pgp_key` are required. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/generate-root/attempt` | `200 application/json` | + +### Parameters + +- `otp` `(string: )` – Specifies a base64-encoded 16-byte + value. The raw bytes of the token will be XOR'd with this value before being + returned to the final unseal key provider. + +- `pgp_key` `(string: )` – Specifies a base64-encoded PGP + public key. The raw bytes of the token will be encrypted with this value + before being returned to the final unseal key provider. + +### Sample Payload + +```json +{ + "otp": "CB23==" +} +``` + +### Sample Request + +``` +$ curl \ + --request PUT \ + --data payload.json \ + https://vault.rocks/v1/sys/generate-root/attempt +``` + +### Sample Response + +```json +{ + "started": true, + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "progress": 1, + "required": 3, + "encoded_root_token": "", + "pgp_fingerprint": "816938b8a29146fbe245dd29e7cbaf8e011db793", + "complete": false +} +``` + +## Cancel Root Generation + +This endpoint cancels any in-progress root generation attempt. This clears any +progress made. This must be called to change the OTP or PGP key being used. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/generate-root/attempt` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --request DELETE \ + https://vault.rocks/v1/sys/generate-root/attempt +``` + +## Provide Key Share to Generate Root + +This endpoint is used to enter a single master key share to progress the root +generation attempt. If the threshold number of master key shares is reached, +Vault will complete the root generation and issue the new token. Otherwise, +this API must be called multiple times until that threshold is met. The attempt +nonce must be provided with each call. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/generate-root/update` | `200 application/json` | + +### Parameters + +- `key` `(string: )` – Specifies a single master key share. + +- `nonce` `(string: )` – Specifies the nonce of the attempt. + +### Sample Payload + +```json +{ + "key": "acbd1234", + "nonce": "ad235", +} +``` + +### Sample Request + +``` +$ curl \ + --request PUT \ + --data payload.json \ + https://vault.rocks/v1/sys/generate-root/update +``` + +### Sample Response + +This returns a JSON-encoded object indicating the attempt nonce, and completion +status, and the encoded root token, if the attempt is complete. + +```json +{ + "started": true, + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "progress": 3, + "required": 3, + "pgp_fingerprint": "", + "complete": true, + "encoded_root_token": "FPzkNBvwNDeFh4SmGA8c+w==" +} +``` diff --git a/website/source/docs/http/system/health.html.md b/website/source/docs/http/system/health.html.md new file mode 100644 index 000000000..2b9322b5e --- /dev/null +++ b/website/source/docs/http/system/health.html.md @@ -0,0 +1,71 @@ +--- +layout: "http" +page_title: "/sys/health - HTTP API" +sidebar_current: "docs-http-system-health" +description: |- + The `/sys/health` endpoint is used to check the health status of Vault. +--- + +# `/sys/health` + +The `/sys/health` endpoint is used to check the health status of Vault. + +## Read Health Information + +This endpoint returns the health status of Vault. This matches the semantics of +a Consul HTTP health check and provides a simple way to monitor the health of a +Vault instance. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `HEAD` | `/sys/health` | `000 (empty body)` | +| `GET` | `/sys/health` | `000 application/json` | + +The default status codes are: + +- `200` if initialized, unsealed, and active +- `429` if unsealed and standby +- `501` if not initialized +- `503` if sealed + +### Parameters + +- `standbyok` `(bool: false)` – Specifies if being a standby should still return + the active status code instead of the standby status code. This is useful when + Vault is behind a non-configurable load balance that just wants a 200-level + response. + +- `activecode` `(int: 200)` – Specifies the status code that should be returned + for an active node. + +- `standbycode` `(int: 429)` – Specifies the status code that should be returned + for a standby node. + +- `sealedcode` `(int: 503)` – Specifies the status code that should be returned + for a sealed node. + +- `uninitcode` `(int: 501)` – Specifies the status code that should be returned + for a uninitialized node. + +### Sample Request + +``` +$ curl \ + https://vault.rocks/v1/sys/health +``` + +### Sample Response + +This response is only returned for a `GET` request. + +```json +{ + "cluster_id": "c9abceea-4f46-4dab-a688-5ce55f89e228", + "cluster_name": "vault-cluster-5515c810", + "version": "0.6.2", + "server_time_utc": 1469555798, + "standby": false, + "sealed": false, + "initialized": true +} +``` diff --git a/website/source/docs/http/system/index.html.md b/website/source/docs/http/system/index.html.md new file mode 100644 index 000000000..f78d1e927 --- /dev/null +++ b/website/source/docs/http/system/index.html.md @@ -0,0 +1,17 @@ +--- +layout: "http" +page_title: "System Backend - HTTP API" +sidebar_current: "docs-http-system" +description: |- + The system backend is a default backend in Vault that is mounted at the `/sys` + endpoint. This endpoint cannot be unmounted or moved, and is used to configure + Vault and interact with many of Vault's internal features. +--- + +# System Backend + +The system backend is a default backend in Vault that is mounted at the `/sys` +endpoint. This endpoint cannot be unmounted or moved, and is used to configure +Vault and interact with many of Vault's internal features. + +For more information about a particular path, please click on it in the sidebar. diff --git a/website/source/docs/http/system/init.html.md b/website/source/docs/http/system/init.html.md new file mode 100644 index 000000000..940211d81 --- /dev/null +++ b/website/source/docs/http/system/init.html.md @@ -0,0 +1,112 @@ +--- +layout: "http" +page_title: "/sys/init - HTTP API" +sidebar_current: "docs-http-system-init" +description: |- + The `/sys/init` endpoint is used to initialize a new Vault. +--- + +# `/sys/init` + +The `/sys/init` endpoint is used to initialize a new Vault. + +## Read Initialization Status + +This endpoint returns the initialization status of Vault. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/init` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + https://vault.rocks/v1/sys/init +``` + +### Sample Response + +```json +{ + "initialized": true +} +``` + +## Start Initialization + +This endpoint initializes a new Vault. The Vault must not have been previously +initialized. The recovery options, as well as the stored shares option, are only +available when using Vault HSM. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/init` | `200 application/json` | + +### Parameters + +- `pgp_keys` `(array: nil)` – Specifies an array of PGP public keys used + to encrypt the output unseal keys. Ordering is preserved. The keys must be + base64-encoded from their original binary representation. The size of this + array must be the same as `secret_shares`. + +- `root_token_pgp_key` `(string: "")` – Specifies a PGP public key used to + encrypt the initial root token. The key must be base64-encoded from its + original binary representation. + +- `secret_shares` `(int: )` – Specifies the number of shares to + split the master key into. + +- `secret_threshold` `(int: )` – Specifies the number of shares + required to reconstruct the master key. This must be less than or equal + `secret_shares`. If using Vault HSM with auto-unsealing, this value must be + the same as `secret_shares`. + +Additionally, the following options are only supported on Vault Pro/Enterprise: + +- `stored_shares` `(int: )` – Specifies the number of shares that + should be encrypted by the HSM and stored for auto-unsealing. Currently must + be the same as `secret_shares`. + +- `recovery_shares` `(int: )` – Specifies rhe number of shares to + split the recovery key into. + +- `recovery_threshold` `(int: )` – Specifies rhe number of shares + required to reconstruct the recovery key. This must be less than or equal to + `recovery_shares`. + +- `recovery_pgp_keys` `(array: nil)` – Specifies an array of PGP public + keys used to encrypt the output recovery keys. Ordering is preserved. The keys + must be base64-encoded from their original binary representation. The size of + this array must be the same as `recovery_shares`. + +### Sample Payload + +```json +{ + "secret_shares": 10, + "secret_threshold": 5 +} +``` + +### Sample Request + +``` +$ curl \ + --request PUT \ + --data payload.json \ + https://vault.rocks/v1/sys/init +``` + +### Sample Response + +A JSON-encoded object including the (possibly encrypted, if `pgp_keys` was +provided) master keys, base 64 encoded master keys and initial root token: + +```json +{ + "keys": ["one", "two", "three"], + "keys_base64": ["cR9No5cBC", "F3VLrkOo", "zIDSZNGv"], + "root_token": "foo" +} +``` diff --git a/website/source/docs/http/system/key-status.html.md b/website/source/docs/http/system/key-status.html.md new file mode 100644 index 000000000..e7451494f --- /dev/null +++ b/website/source/docs/http/system/key-status.html.md @@ -0,0 +1,37 @@ +--- +layout: "http" +page_title: "/sys/key-status - HTTP API" +sidebar_current: "docs-http-system-key-status" +description: |- + The `/sys/key-status` endpoint is used to query info about the current + encryption key of Vault. +--- + +# `/sys/key-status` + +The `/sys/key-status` endpoint is used to query info about the current +encryption key of Vault. + +## Get Encryption Key Status + +This endpoint returns information about the current encryption key used by +Vault. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/key-status` | `200 application/json` | + + +### Sample Request + +### Sample Response + +```json +{ + "term": 3, + "install_time": "2015-05-29T14:50:46.223692553-07:00" +} +``` + +The `term` parameter is the sequential key number, and `install_time` is the +time that encryption key was installed. diff --git a/website/source/docs/http/system/leader.html.md b/website/source/docs/http/system/leader.html.md new file mode 100644 index 000000000..81200be13 --- /dev/null +++ b/website/source/docs/http/system/leader.html.md @@ -0,0 +1,39 @@ +--- +layout: "http" +page_title: "/sys/leader - HTTP API" +sidebar_current: "docs-http-system-leader" +description: |- + The `/sys/leader` endpoint is used to check the high availability status and + current leader of Vault. +--- + +# `/sys/leader` + +The `/sys/leader` endpoint is used to check the high availability status and +current leader of Vault. + +## Read Leader Status + +This endpoint returns the high availability status and current leader instance +of Vault. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/leader` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + https://vault.rocks/v1/sys/leader +``` + +### Sample Response + +```json +{ + "ha_enabled": true, + "is_self": false, + "leader_address": "https://127.0.0.1:8200/" +} +``` diff --git a/website/source/docs/http/system/mounts.html.md b/website/source/docs/http/system/mounts.html.md new file mode 100644 index 000000000..27826f280 --- /dev/null +++ b/website/source/docs/http/system/mounts.html.md @@ -0,0 +1,188 @@ +--- +layout: "http" +page_title: "/sys/mounts - HTTP API" +sidebar_current: "docs-http-system-mounts" +description: |- + The `/sys/mounts` endpoint is used manage secret backends in Vault. +--- + +# `/sys/mounts` + +The `/sys/mounts` endpoint is used manage secret backends in Vault. + +## List Mounted Secret Backends + +This endpoints lists all the mounted secret backends. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/mounts` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/mounts +``` + +### Sample Response + +```json +{ + "aws": { + "type": "aws", + "description": "AWS keys", + "config": { + "default_lease_ttl": 0, + "max_lease_ttl": 0, + "force_no_cache": false + } + }, + "sys": { + "type": "system", + "description": "system endpoint", + "config": { + "default_lease_ttl": 0, + "max_lease_ttl": 0, + "force_no_cache": false + } + } +} +``` + +`default_lease_ttl` or `max_lease_ttl` values of 0 mean that the system defaults +are used by this backend. + +## Mount Secret Backend + +This endpoint mounts a new secret backend at the given path. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/mounts/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path where the secret backend + will be mounted. This is specified as part of the URL. + +- `type` `(string: )` – Specifies the type of the backend, such as + "aws". + +- `description` `(string: "")` – Specifies the human-friendly description of the + mount. + +- `config` `(map: nil)` – Specifies configuration options for + this mount. This is an object with three possible values: + + - `default_lease_ttl` + - `max_lease_ttl` + - `force_no_cache` + + These control the default and maximum lease time-to-live, and force + disabling backend caching respectively. If set on a specific mount, this + overrides the global defaults. + +### Sample Payload + +```json +{ + "type": "aws", + "config": { + "force_no_cache": true + } +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data payload.json \ + https://vault.rocks/v1/sys/mounts/my-mount +``` + +## Unmount Secret Backend + +This endpoint un-mounts the mount point specified in the URL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/mounts/:path` | `204 (empty body) ` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/mounts/my-mount +``` + +## Read Mount Configuration + +This endpoint reads the given mount's configuration. Unlike the `mounts` +endpoint, this will return the current time in seconds for each TTL, which may +be the system default or a mount-specific value. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/mounts/:path/tune` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/mounts/my-mount/tune +``` + +### Sample Response + +```json +{ + "default_lease_ttl": 3600, + "max_lease_ttl": 7200, + "force_no_cache": false +} +``` + +## Tune Mount Configuration + +This endpoint tunes configuration parameters for a given mount point. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/mounts/:path/tune` | `204 (empty body)` | + +### Parameters + +- `default_lease_ttl` `(int: 0)` – Specifies the default time-to-live. This + overrides the global default. A value of `0` is equivalent to the system + default TTL. + +- `max_lease_ttl` `(int: 0)` – Specifies the maximum time-to-live. This + overrides the global default. A value of `0` are equivalent and set to the + system max TTL. + +### Sample Payload + +```json +{ + "default_lease_ttl": 1800, + "max_lease_ttl": 3600 +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data payload.json \ + https://vault.rocks/v1/sys/mounts/my-mount/tune +``` diff --git a/website/source/docs/http/system/policy.html.md b/website/source/docs/http/system/policy.html.md new file mode 100644 index 000000000..8a2137354 --- /dev/null +++ b/website/source/docs/http/system/policy.html.md @@ -0,0 +1,121 @@ +--- +layout: "http" +page_title: "/sys/policy - HTTP API" +sidebar_current: "docs-http-system-policy" +description: |- + The `/sys/policy` endpoint is used to manage ACL policies in Vault. +--- + +# `/sys/policy` + +The `/sys/policy` endpoint is used to manage ACL policies in Vault. + +## List Policies + +This endpoint lists all configured policies. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/policy` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/policy +``` + +### Sample Response + +```json +{ + "policies": ["root", "deploy"] +} +``` + +## Read Policy + +This endpoint retrieve the rules for the named policy. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/policy/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the policy to retrieve. + This is specified as part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/policy/my-policy +``` + +### Sample Response + +```json +{ + "rules": "path \"secret/foo\" {..." +} +``` + +## Create/Update Policy + +This endpoint adds a new or updates an existing policy. Once a policy is +updated, it takes effect immediately to all associated users. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/policy/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the policy to create. + This is specified as part of the request URL. + +- `rules` `(string: )` - Specifies the policy document. + +### Sample Payload + +```json +{ + "rules": "path \"secret/foo\" {..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data payload.json \ + https://vault.rocks/v1/sys/policy/my-policy +``` + +## Delete Policy + +This endpoint deletes the policy with the given name. This will immediately +affect all users associated with this policy. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/policy/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the policy to delete. + This is specified as part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/policy/my-policy +``` diff --git a/website/source/docs/http/system/raw.html.md b/website/source/docs/http/system/raw.html.md new file mode 100644 index 000000000..57ee5a225 --- /dev/null +++ b/website/source/docs/http/system/raw.html.md @@ -0,0 +1,100 @@ +--- +layout: "http" +page_title: "/sys/raw - HTTP API" +sidebar_current: "docs-http-system-raw" +description: |- + The `/sys/raw` endpoint is access the raw underlying store in Vault. +--- + +# `/sys/raw` + +The `/sys/raw` endpoint is access the raw underlying store in Vault. + +## Read Raw + +This endpoint reads the value of the key at the given path. This is the raw path +in the storage backend and not the logical path that is exposed via the mount +system. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/raw/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the raw path in the storage backend. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + ---header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/raw/secret/foo +``` + +### Sample Response + +```json +{ + "value": "{'foo':'bar'}" +} +``` + +## Create/Update Raw + +This endpoint updates the value of the key at the given path. This is the raw +path in the storage backend and not the logical path that is exposed via the +mount system. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/raw/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the raw path in the storage backend. + This is specified as part of the URL. + +- `value` `(string: )` – Specifies the value of the key. + +### Sample Payload + +```json +{ + "value": "{\"foo\": \"bar\"}" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/raw/secret/foo +``` + +## Delete Raw + +This endpoint deletes the key with given path. This is the raw path in the +storage backend and not the logical path that is exposed via the mount system. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/raw/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the raw path in the storage backend. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/raw/secret/foo +``` diff --git a/website/source/docs/http/system/rekey.html.md b/website/source/docs/http/system/rekey.html.md new file mode 100644 index 000000000..b3a61604f --- /dev/null +++ b/website/source/docs/http/system/rekey.html.md @@ -0,0 +1,217 @@ +--- +layout: "http" +page_title: "/sys/rekey - HTTP API" +sidebar_current: "docs-http-system-rekey" +description: |- + The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault. +--- + +# `/sys/rekey` + +The `/sys/rekey` endpoints are used to rekey the unseal keys for Vault. + +## Read Rekey Progress + +This endpoint reads the configuration and progress of the current rekey attempt. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/rekey/init` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/rekey/init +``` + +### Sample Response + +```json +{ + "started": true, + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "t": 3, + "n": 5, + "progress": 1, + "required": 3, + "pgp_fingerprints": ["abcd1234"], + "backup": true +} +``` + +If a rekey is started, then `n` is the new shares to generate and `t` is the +threshold required for the new shares. `progress` is how many unseal keys have +been provided for this rekey, where `required` must be reached to complete. The +`nonce` for the current rekey operation is also displayed. If PGP keys are being +used to encrypt the final shares, the key fingerprints and whether the final +keys will be backed up to physical storage will also be displayed. + + +## Start Rekey + +This endpoint initializes a new rekey attempt. Only a single rekey attempt can +take place at a time, and changing the parameters of a rekey requires canceling +and starting a new rekey, which will also provide a new nonce. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/rekey/init` | `204 (empty body)` | + +### Parameters + +- `secret_shares` `(int: )` – Specifies the number of shares to split + the master key into. + +- `secret_threshold` `(int: )` – Specifies the number of shares + required to reconstruct the master key. This must be less than or equal to + `secret_shares`. + +- `pgp_keys` `(array: nil)` – Specifies an array of PGP public keys used + to encrypt the output unseal keys. Ordering is preserved. The keys must be + base64-encoded from their original binary representation. The size of this + array must be the same as `secret_shares`. + +- `backup` `(bool: false)` – Specifies if using PGP-encrypted keys, whether + Vault should also back them up to `core/unseal-keys-backup` in the physical + storage backend. These can then be retrieved and removed via the + `sys/rekey/backup` endpoint. + +### Sample Payload + +```json +{ + "secret_shares": 10, + "secret_threshold": 5 +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/rekey/init +``` + +## Cancel Rekey + +This endpoint cancels any in-progress rekey. This clears the rekey settings as +well as any progress made. This must be called to change the parameters of the +rekey. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/rekey/init` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/sys/rekey/init +``` + +## Read Backup Key + +This endpoint returns the backup copy of PGP-encrypted unseal keys. The returned +value is the nonce of the rekey operation and a map of PGP key fingerprint to +hex-encoded PGP-encrypted key. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/rekey/backup` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/rekey/backup +``` + +### Sample Response + +```json +{ + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "keys": { + "abcd1234": "..." + } +} +``` + +## Delete Backup Key + +This endpoint deletes the backup copy of PGP-encrypted unseal keys. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/sys/rekey/backup` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request DELETE \ + https://vault.rocks/v1/sys/rekey/backup +``` + +## Submit Key + +This endpoint is used to enter a single master key share to progress the rekey +of the Vault. If the threshold number of master key shares is reached, Vault +will complete the rekey. Otherwise, this API must be called multiple times until +that threshold is met. The rekey nonce operation must be provided with each +call. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/rekey/update` | `200 application/json` | + +### Parameters + +- `key` `(string: )` – Specifies a single master share key. + +- `nonce` `(string: )` – Specifies the nonce of the rekey operation. + +### Sample Payload + +```json +{ + "key": "abcd1234...", + "nonce": "AB32..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token" \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/rekey/update +``` + +### Sample Response + +```json +{ + "complete": true, + "keys": ["one", "two", "three"], + "nonce": "2dbd10f1-8528-6246-09e7-82b25b8aba63", + "pgp_fingerprints": ["abcd1234"], + "keys_base64": ["base64keyvalue"], + "backup": true +} +``` + +If the keys are PGP-encrypted, an array of key fingerprints will also be +provided (with the order in which the keys were used for encryption) along with +whether or not the keys were backed up to physical storage. diff --git a/website/source/docs/http/system/remount.html.md b/website/source/docs/http/system/remount.html.md new file mode 100644 index 000000000..8092984b3 --- /dev/null +++ b/website/source/docs/http/system/remount.html.md @@ -0,0 +1,44 @@ +--- +layout: "http" +page_title: "/sys/remount - HTTP API" +sidebar_current: "docs-http-system-remount" +description: |- + The '/sys/remount' endpoint is used remount a mounted backend to a new endpoint. +--- + +# `/sys/remount` + +The `/sys/remount` endpoint is used remount a mounted backend to a new endpoint. + +## Remount Backend + +This endpoint remounts an already-mounted backend to a new mount point. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/remount` | `204 (empty body)` | + +### Parameters + +- `from` `(string: )` – Specifies the previous mount point. + +- `to` `(string: )` – Specifies the new destination mount point. + +### Sample Payload + +```json +{ + "from": "secret", + "to": "new-secret" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/remount +``` diff --git a/website/source/docs/http/system/renew.html.md b/website/source/docs/http/system/renew.html.md new file mode 100644 index 000000000..cbf05efc8 --- /dev/null +++ b/website/source/docs/http/system/renew.html.md @@ -0,0 +1,68 @@ +--- +layout: "http" +page_title: "/sys/renew - HTTP API" +sidebar_current: "docs-http-system-renew" +description: |- + The `/sys/renew` endpoint is used to renew secrets. +--- + +# `/sys/renew` + +The `/sys/renew` endpoint is used to renew secrets. + +## Renew Secret + +This endpoint renews a secret, requesting to extend the lease. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/renew/(:lease_id)` | `200 application/json` | + +### Parameters + +- `lease_id` `(string: )` – Specifies the ID of the lease to extend. + This can be specified as part of the URL or as part of the request body. + +- `increment` `(int: 0)` – Specifies the requested amount of time (in seconds) + to extend the lease. + +### Sample Payload + +```json +{ + "lease_id": "postgresql/creds/readonly/abcd-1234...", + "increment": 1800 +} +``` + +### Sample Request + +With the `lease_id` as part of the URL: + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/renew/postgresql/creds/readonly/abcd-1234 +``` + +With the `lease_id` in the request body: + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/renew +``` + +### Sample Response + +```json +{ + "lease_id": "aws/creds/deploy/e31b1145-ff27-e62c-cba2-934e9f0d1dbc", + "renewable": true, + "lease_duration": 2764790 +} +``` diff --git a/website/source/docs/http/system/revoke-force.html.md b/website/source/docs/http/system/revoke-force.html.md new file mode 100644 index 000000000..ceac319bf --- /dev/null +++ b/website/source/docs/http/system/revoke-force.html.md @@ -0,0 +1,43 @@ +--- +layout: "http" +page_title: "/sys/revoke-force - HTTP API" +sidebar_current: "docs-http-system-revoke-force" +description: |- + The `/sys/revoke-force` endpoint is used to revoke secrets or tokens based on + prefix while ignoring backend errors. +--- + +# `/sys/revoke-force` + +The `/sys/revoke-force` endpoint is used to revoke secrets or tokens based on +prefix while ignoring backend errors. + +## Revoke Force + +This endpoint revokes all secrets or tokens generated under a given prefix +immediately. Unlike `/sys/revoke-prefix`, this path ignores backend errors +encountered during revocation. This is _potentially very dangerous_ and should +only be used in specific emergency situations where errors in the backend or the +connected backend service prevent normal revocation. + +By ignoring these errors, Vault abdicates responsibility for ensuring that the +issued credentials or secrets are properly revoked and/or cleaned up. Access to +this endpoint should be tightly controlled. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/revoke-force/:prefix` | `204 (empty body)` | + +### Parameters + +- `prefix` `(string: )` – Specifies the prefix to revoke. This is + specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + https://vault.rocks/v1/sys/revoke-force/aws/creds +``` diff --git a/website/source/docs/http/system/revoke-prefix.html.md b/website/source/docs/http/system/revoke-prefix.html.md new file mode 100644 index 000000000..ea3aa9b16 --- /dev/null +++ b/website/source/docs/http/system/revoke-prefix.html.md @@ -0,0 +1,38 @@ +--- +layout: "http" +page_title: "/sys/revoke-prefix - HTTP API" +sidebar_current: "docs-http-system-revoke-prefix" +description: |- + The `/sys/revoke-prefix` endpoint is used to revoke secrets or tokens based on + prefix. +--- + +# `/sys/revoke-prefix` + +The `/sys/revoke-prefix` endpoint is used to revoke secrets or tokens based on +prefix. + +## Revoke Prefix + +This endpoint revokes all secrets (via a lease ID prefix) or tokens (via the +tokens' path property) generated under a given prefix immediately. This requires +`sudo` capability and access to it should be tightly controlled as it can be +used to revoke very large numbers of secrets/tokens at once. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/revoke-prefix/:prefix` | `204 (empty body)` | + +### Parameters + +- `prefix` `(string: )` – Specifies the prefix to revoke. This is + specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + https://vault.rocks/v1/sys/revoke-prefix/aws/creds +``` diff --git a/website/source/docs/http/system/revoke.html.md b/website/source/docs/http/system/revoke.html.md new file mode 100644 index 000000000..f670e889c --- /dev/null +++ b/website/source/docs/http/system/revoke.html.md @@ -0,0 +1,32 @@ +--- +layout: "http" +page_title: "/sys/revoke - HTTP API" +sidebar_current: "docs-http-system-revoke/" +description: |- + The `/sys/revoke` endpoint is used to revoke secrets. +--- + +# `/sys/revoke` + +The `/sys/revoke` endpoint is used to revoke secrets. + +## Revoke Secret + +This endpoint revokes a secret immediately. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/revoke/:lease_id` | `204 (empty body)` | + +### Parameters + +- `lease_id` `(string: )` – Specifies the ID of the lease to renew. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + https://vault.rocks/v1/sys/revoke/aws/creds/readonly-acbd1234 +``` diff --git a/website/source/docs/http/system/rotate.html.md b/website/source/docs/http/system/rotate.html.md new file mode 100644 index 000000000..69f6d86f0 --- /dev/null +++ b/website/source/docs/http/system/rotate.html.md @@ -0,0 +1,31 @@ +--- +layout: "http" +page_title: "/sys/rotate - HTTP API" +sidebar_current: "docs-http-system-rotate" +description: |- + The `/sys/rotate` endpoint is used to rotate the encryption key. +--- + +# `/sys/rotate` + +The `/sys/rotate` endpoint is used to rotate the encryption key. + +## Rotate Encryption Key + +This endpoint triggers a rotation of the backend encryption key. This is the key +that is used to encrypt data written to the storage backend, and is not provided +to operators. This operation is done online. Future values are encrypted with +the new key, while old values are decrypted with previous encryption keys. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/rotate` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + https://vault.rocks/v1/sys/rotate +``` diff --git a/website/source/docs/http/system/seal-status.html.md b/website/source/docs/http/system/seal-status.html.md new file mode 100644 index 000000000..239362939 --- /dev/null +++ b/website/source/docs/http/system/seal-status.html.md @@ -0,0 +1,55 @@ +--- +layout: "http" +page_title: "/sys/seal-status - HTTP API" +sidebar_current: "docs-http-system-seal-status" +description: |- + The `/sys/seal-status` endpoint is used to check the seal status of a Vault. +--- + +# `/sys/seal-status` + +The `/sys/seal-status` endpoint is used to check the seal status of a Vault. + +## Seal Status + +This endpoint returns the seal status of the Vault. This is an unauthenticated +endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/seal-status` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + https://vault.rocks/v1/sys/seal-status +``` + +### Sample Response + +The "t" parameter is the threshold, and "n" is the number of shares. + +```json +{ + "sealed": true, + "t": 3, + "n": 5, + "progress": 2, + "version": "0.6.2" +} +``` + +Sample response when Vault is unsealed. + +```json +{ + "sealed": false, + "t": 3, + "n": 5, + "progress": 0, + "version": "0.6.2", + "cluster_name": "vault-cluster-d6ec3c7f", + "cluster_id": "3e8b3fec-3749-e056-ba41-b62a63b997e8" +} +``` diff --git a/website/source/docs/http/system/seal.html.md b/website/source/docs/http/system/seal.html.md new file mode 100644 index 000000000..59f369f17 --- /dev/null +++ b/website/source/docs/http/system/seal.html.md @@ -0,0 +1,30 @@ +--- +layout: "http" +page_title: "/sys/seal - HTTP API" +sidebar_current: "docs-http-system-seal/" +description: |- + The `/sys/seal` endpoint seals the Vault. +--- + +# `/sys/seal` + +The `/sys/seal` endpoint seals the Vault. + +## Seal + +This endpoint seals the Vault. In HA mode, only an active node can be sealed. +Standby nodes should be restarted to get the same effect. Requires a token with +`root` policy or `sudo` capability on the path. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/seal` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + https://vault.rocks/v1/sys/seal +``` diff --git a/website/source/docs/http/system/step-down.html.md b/website/source/docs/http/system/step-down.html.md new file mode 100644 index 000000000..db39f43bf --- /dev/null +++ b/website/source/docs/http/system/step-down.html.md @@ -0,0 +1,33 @@ +--- +layout: "http" +page_title: "/sys/step-down - HTTP API" +sidebar_current: "docs-http-system-step-down" +description: |- + The `/sys/step-down` endpoint causes the node to give up active status. +--- + +# `/sys/step-down` + +The `/sys/step-down` endpoint causes the node to give up active status. + +## Step Down Leader + +This endpoint forces the node to give up active status. If the node does not +have active status, this endpoint does nothing. Note that the node will sleep +for ten seconds before attempting to grab the active lock again, but if no +standby nodes grab the active lock in the interim, the same node may become the +active node again. Requires a token with `root` policy or `sudo` capability on +the path. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/step-down` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + https://vault.rocks/v1/sys/step-down +``` diff --git a/website/source/docs/http/system/unseal.html.md b/website/source/docs/http/system/unseal.html.md new file mode 100644 index 000000000..e0465f81f --- /dev/null +++ b/website/source/docs/http/system/unseal.html.md @@ -0,0 +1,78 @@ +--- +layout: "http" +page_title: "/sys/seal-unseal - HTTP API" +sidebar_current: "docs-http-system-unseal" +description: |- + The `/sys/seal-unseal` endpoint is used to unseal the Vault. +--- + +# `/sys/unseal` + +The `/sys/seal-unseal` endpoint is used to unseal the Vault. + +## Submit Unseal Key + +This endpoint is used to enter a single master key share to progress the +unsealing of the Vault. If the threshold number of master key shares is reached, +Vault will attempt to unseal the Vault. Otherwise, this API must be called +multiple times until that threshold is met. + +Either the `key` or `reset` parameter must be provided; if both are provided, +`reset` takes precedence. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `PUT` | `/sys/unseal` | `200 application/json` | + +### Parameters + +- `key` `(string: "")` – Specifies a single master key share. This is required + unless `reset` is true. + +- `reset` `(bool: false)` – Specifies if previously-provided unseal keys are + discarded and the unseal process is reset. + +### Sample Payload + +```json +{ + "key": "abcd1234..." +} +``` + +### Sample Request + +``` +$ curl \ + --request PUT \ + --data @payload.json \ + https://vault.rocks/v1/sys/unseal +``` + +### Sample Response + +The "t" parameter is the threshold, and "n" is the number of shares. + +```json +{ + "sealed": true, + "t": 3, + "n": 5, + "progress": 2, + "version": "0.6.2" +} +``` + +Sample response when Vault is unsealed. + +```json +{ + "sealed": false, + "t": 3, + "n": 5, + "progress": 0, + "version": "0.6.2", + "cluster_name": "vault-cluster-d6ec3c7f", + "cluster_id": "3e8b3fec-3749-e056-ba41-b62a63b997e8" +} +``` diff --git a/website/source/docs/http/system/wrapping-lookup.html.md b/website/source/docs/http/system/wrapping-lookup.html.md new file mode 100644 index 000000000..bea4942b1 --- /dev/null +++ b/website/source/docs/http/system/wrapping-lookup.html.md @@ -0,0 +1,57 @@ +--- +layout: "http" +page_title: "/sys/wrapping/lookup - HTTP API" +sidebar_current: "docs-http-system-wrapping-lookup" +description: |- + The `/sys/wrapping/lookup` endpoint returns wrapping token properties. +--- + +# `/sys/wrapping/lookup` + +The `/sys/wrapping/lookup` endpoint returns wrapping token properties. + +## Wrapping Lookup + +This endpoint looks up wrapping properties for the given token. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/wrapping/lookup` | `200 application/json` | + +### Parameters + +- `token` `(string: )` – Specifies the wrapping token ID. + +### Sample Payload + +```json +{ + "token": "abcd1234" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/wrapping/lookup +``` + +### Sample Response + +```json +{ + "request_id": "481320f5-fdf8-885d-8050-65fa767fd19b", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "creation_time": "2016-09-28T14:16:13.07103516-04:00", + "creation_ttl": 300 + }, + "warnings": null +} +``` diff --git a/website/source/docs/http/system/wrapping-rewrap.html.md b/website/source/docs/http/system/wrapping-rewrap.html.md new file mode 100644 index 000000000..edc146922 --- /dev/null +++ b/website/source/docs/http/system/wrapping-rewrap.html.md @@ -0,0 +1,64 @@ +--- +layout: "http" +page_title: "/sys/wrapping/rewrap - HTTP API" +sidebar_current: "docs-http-system-wrapping-rewrap" +description: |- + The `/sys/wrapping/rewrap` endpoint can be used to rotate a wrapping token and refresh its TTL. +--- + +# `/sys/wrapping/rewrap` + +The `/sys/wrapping/rewrap` endpoint can be used to rotate a wrapping token and +refresh its TTL. + +## Wrapping Rewrap + +This endpoint rewraps a response-wrapped token. The new token will use the same +creation TTL as the original token and contain the same response. The old token +will be invalidated. This can be used for long-term storage of a secret in a +response-wrapped token when rotation is a requirement. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/wrapping/rewrap` | `200 application/json` | + +### Parameters + +- `token` `(string: )` – Specifies the wrapping token ID. + +### Sample Payload + +```json +{ + "token": "abcd1234...", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/wrapping/lookup +``` + +### Sample Response + +```json +{ + "request_id": "", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": null, + "warnings": null, + "wrap_info": { + "token": "3b6f1193-0707-ac17-284d-e41032e74d1f", + "ttl": 300, + "creation_time": "2016-09-28T14:22:26.486186607-04:00", + "wrapped_accessor": "" + } +} +``` diff --git a/website/source/docs/http/system/wrapping-unwrap.html.md b/website/source/docs/http/system/wrapping-unwrap.html.md new file mode 100644 index 000000000..1a2b46659 --- /dev/null +++ b/website/source/docs/http/system/wrapping-unwrap.html.md @@ -0,0 +1,69 @@ +--- +layout: "http" +page_title: "/sys/wrapping/unwrap - HTTP API" +sidebar_current: "docs-http-system-wrapping-unwrap" +description: |- + The `/sys/wrapping/unwrap` endpoint unwraps a wrapped response. +--- + +# `/sys/wrapping/unwrap` + +The `/sys/wrapping/unwrap` endpoint unwraps a wrapped response. + +## Wrapping Unwrap + +This endpoint returns the original response inside the given wrapping token. +Unlike simply reading `cubbyhole/response` (which is deprecated), this endpoint +provides additional validation checks on the token, returns the original value +on the wire rather than a JSON string representation of it, and ensures that the +response is properly audit-logged. + +This endpoint can be used by using a wrapping token as the client token in the +API call, in which case the `token` parameter is not required; or, a different +token with permissions to access this endpoint can make the call and pass in the +wrapping token in the `token` parameter. Do _not_ use the wrapping token in both +locations; this will cause the wrapping token to be revoked but the value to be +unable to be looked up, as it will basically be a double-use of the token! + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/wrapping/unwrap` | `200 application/json` | + +### Parameters + +- `token` `(string: "")` – Specifies the wrapping token ID. This is required if + the client token is not the wrapping token. Do not use the wrapping token in + both locations. + +### Sample Payload + +```json +{ + "token": "abcd1234..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/wrapping/unwrap +``` + +### Sample Response + +```json +{ + "request_id": "8e33c808-f86c-cff8-f30a-fbb3ac22c4a8", + "lease_id": "", + "lease_duration": 2592000, + "renewable": false, + "data": { + "zip": "zap" + }, + "warnings": null +} +``` diff --git a/website/source/docs/http/system/wrapping-wrap.html.md b/website/source/docs/http/system/wrapping-wrap.html.md new file mode 100644 index 000000000..7a43a3df0 --- /dev/null +++ b/website/source/docs/http/system/wrapping-wrap.html.md @@ -0,0 +1,66 @@ +--- +layout: "http" +page_title: "/sys/wrapping/wrap - HTTP API" +sidebar_current: "docs-http-system-wrapping-wrap" +description: |- + The `/sys/wrapping/wrap` endpoint wraps the given values in a + response-wrapped token. +--- + +# `/sys/wrapping/wrap` + +The `/sys/wrapping/wrap` endpoint wraps the given values in a response-wrapped +token. + +## Wrapping Wrap + +This endpoint wraps the given user-supplied data inside a response-wrapped +token. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/wrapping/wrap` | `200 application/json` | + +### Parameters + +- `:any` `(map: nil)` – Parameters should be supplied as + keys/values in a JSON object. The exact set of given parameters will be + contained in the wrapped response. + +### Sample Payload + +```json +{ + "foo": "bar", + "zip": "zap" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/wrapping/wrap +``` + +### Sample Response + +```json +{ + "request_id": "", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": null, + "warnings": null, + "wrap_info": { + "token": "fb79b9d3-d94e-9eb6-4919-c559311133d6", + "ttl": 300, + "creation_time": "2016-09-28T14:41:00.56961496-04:00", + "wrapped_accessor": "" + } +} +``` From 3fd0bd36cc1a2245399a1d41350f757d9bd66fae Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Wed, 8 Mar 2017 18:47:35 -0800 Subject: [PATCH 06/17] Break out API documentation for secret backends --- website/source/assets/stylesheets/_docs.scss | 1 + website/source/docs/http/index.html.md | 4 +- .../source/docs/http/secret/aws/index.html.md | 357 ++++ .../docs/http/secret/cassandra/index.html.md | 245 +++ .../docs/http/secret/consul/index.html.md | 201 +++ .../docs/http/secret/cubbyhole/index.html.md | 155 ++ .../docs/http/secret/generic/index.html.md | 159 ++ website/source/docs/http/secret/index.html.md | 19 + .../docs/http/secret/mongodb/index.html.md | 344 ++++ .../docs/http/secret/mssql/index.html.md | 244 +++ .../docs/http/secret/mysql/index.html.md | 265 +++ .../source/docs/http/secret/pki/index.html.md | 1456 +++++++++++++++++ .../docs/http/secret/postgresql/index.html.md | 259 +++ .../docs/http/secret/rabbitmq/index.html.md | 218 +++ .../source/docs/http/secret/ssh/index.html.md | 861 ++++++++++ .../docs/http/secret/transit/index.html.md | 859 ++++++++++ website/source/docs/secrets/aws/index.html.md | 345 +--- .../docs/secrets/cassandra/index.html.md | 262 +-- .../source/docs/secrets/consul/index.html.md | 184 +-- .../docs/secrets/cubbyhole/index.html.md | 139 +- .../source/docs/secrets/generic/index.html.md | 145 +- .../source/docs/secrets/mongodb/index.html.md | 368 +---- .../source/docs/secrets/mssql/index.html.md | 301 +--- .../source/docs/secrets/mysql/index.html.md | 311 +--- website/source/docs/secrets/pki/index.html.md | 1435 +--------------- .../docs/secrets/postgresql/index.html.md | 290 +--- .../docs/secrets/rabbitmq/index.html.md | 219 +-- website/source/docs/secrets/ssh/index.html.md | 852 +--------- .../source/docs/secrets/transit/index.html.md | 927 +---------- website/source/layouts/docs.erb | 8 +- website/source/layouts/http.erb | 316 ++-- 31 files changed, 5833 insertions(+), 5916 deletions(-) create mode 100644 website/source/docs/http/secret/aws/index.html.md create mode 100644 website/source/docs/http/secret/cassandra/index.html.md create mode 100644 website/source/docs/http/secret/consul/index.html.md create mode 100644 website/source/docs/http/secret/cubbyhole/index.html.md create mode 100644 website/source/docs/http/secret/generic/index.html.md create mode 100644 website/source/docs/http/secret/index.html.md create mode 100644 website/source/docs/http/secret/mongodb/index.html.md create mode 100644 website/source/docs/http/secret/mssql/index.html.md create mode 100644 website/source/docs/http/secret/mysql/index.html.md create mode 100644 website/source/docs/http/secret/pki/index.html.md create mode 100644 website/source/docs/http/secret/postgresql/index.html.md create mode 100644 website/source/docs/http/secret/rabbitmq/index.html.md create mode 100644 website/source/docs/http/secret/ssh/index.html.md create mode 100644 website/source/docs/http/secret/transit/index.html.md diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index 9518ab0e2..5d7ba26cc 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -7,6 +7,7 @@ $docs-font-size: 15px; body.layout-docs, body.layout-inner, body.layout-downloads, +body.layout-http, body.layout-intro { >.container { .col-md-8[role=main] { diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md index a4c232e07..0fb620b3c 100644 --- a/website/source/docs/http/index.html.md +++ b/website/source/docs/http/index.html.md @@ -8,6 +8,8 @@ description: |- # HTTP API +The Vault HTTP API is a + The Vault HTTP API gives you full access to Vault via HTTP. Every aspect of Vault can be controlled via this API. The Vault CLI uses the HTTP API to access Vault. @@ -170,5 +172,5 @@ The following HTTP status codes are used throughout the API. ## Limits -A maximum request size of 32MB is imposed to prevent a denial +A maximum request size of 32MB is imposed to prevent a denial of service attack with arbitrarily large requests. diff --git a/website/source/docs/http/secret/aws/index.html.md b/website/source/docs/http/secret/aws/index.html.md new file mode 100644 index 000000000..d130c5f57 --- /dev/null +++ b/website/source/docs/http/secret/aws/index.html.md @@ -0,0 +1,357 @@ +--- +layout: "http" +page_title: "HTTP API" +sidebar_current: "docs-http-secret-aws" +description: |- + TODO +--- + +# AWS Secret Backend HTTP API + +This is the API documentation for the Vault AWS secret backend. For general +information about the usage and operation of the AWS backend, please see the +[Vault AWS backend documentation](/docs/secrets/aws/index.html). + +This documentation assumes the AWS backend is mounted at the `/aws` path in +Vault. Since it is possible to mount secret backends at any location, please +update your API calls accordingly. + +## Configure Root IAM Credentials + +This endpoint configures the root IAM credentials to communicate with AWS. There +are multiple ways to pass root IAM credentials to the Vault server, specified +below with the highest precedence first. If credentials already exist, this will +overwrite them. + +- Static credentials provided to the API as a payload + +- Credentials in the `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, and `AWS_REGION` + environment variables **on the server** + +- Querying the EC2 metadata service if the **Vault server** is on EC2 and has + querying capabilities + +At present, this endpoint does not confirm that the provided AWS credentials are +valid AWS credentials with proper permissions. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/config/root` | `204 (empty body)` | + +### Parameters + +- `access_key` `(string: )` – Specifies the AWS access key ID. + +- `secret_key` `(string: )` – Specifies the AWS secret access key. + +- `region` `(string: )` – Specifies the AWS region. + +### Sample Payload + +```json +{ + "access_key": "AKIA...", + "secret_key": "2J+...", + "region": "us-east-1" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/config/root +``` + +## Configure Lease + +This endpoint configures lease settings for the AWS secret backend. It is +optional, as there are default values for `lease` and `lease_max`. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "30m", + "lease_max": "12h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/config/lease +``` + +## Read Lease + +This endpoint returns the current lease settings for the AWS secret backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/aws/config/lease` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/aws/config/lease +``` + +### Sample Response + +```json +{ + "data": { + "lease": "30m0s", + "lease_max": "12h0m0s" + } +} +``` + +## Create/Update Role + +This endpoint creates or updates the role with the given `name`. If a role with +the name does not exist, it will be created. If the role exists, it will be +updated with the new attributes. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is part of the request URL. + +- `policy` `(string: )` – Specifies the IAM policy + in JSON format. + +- `arn` `(string: )` – Specifies the full ARN + reference to the desired existing policy. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/roles/example-role +``` + +### Sample Payloads + +Using an inline IAM policy: + +```json +{ + "policy": "{\"Version\": \"...\"}", +} +``` + +Using an ARN: + +```json +{ + "arn": "arn:aws:iam::123456789012:user/David" +} +``` + +## Read Role + +This endpoint queries an existing role by the given name. If the role does not +exist, a 404 is returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/aws/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/aws/roles/example-role +``` + +### Sample Responses + +For an inline IAM policy: + +```json +{ + "data": { + "policy": "{\"Version\": \"...\"}" + } +} +``` + +For an ARN: + +```json +{ + "data": { + "arn": "arn:aws:iam::123456789012:user/David" + } +} +``` + +## List Roles + +This endpoint lists all existing roles in the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/aws/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/aws/roles +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "example-role" + ] + } +} +``` + +## Delete Role + +This endpoint deletes an existing role by the given name. If the role does not +exist, a 404 is returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELET` | `/aws/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/aws/roles/example-role +``` + +## Generate IAM Credentials + +This endpoint generates dynamic IAM credentials based on the named role. This +role must be created before queried. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/aws/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to generate + credentials againts. This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/aws/creds/example-role +``` + +### Sample Response + +```json +{ + "data": { + "access_key": "AKIA...", + "secret_key": "xlCs...", + "security_token": null + } +} +``` + +## Generate IAM with STS + +This generates a dynamic IAM credential with an STS token based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/aws/sts/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role against which + to create this STS credential. This is part of the request URL. + +- `ttl` `(string: "3600s")` – Specifies the TTL for the use of the STS token. + This is specified as a string with a duration suffix. + +### Sample Payload + +```json +{ + "ttl": "5m" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/aws/sts/example-role +``` + +### Sample Response + +```json +{ + "data": { + "access_key": "AKIA...", + "secret_key": "xlCs...", + "security_token": "429255" + } +} +``` diff --git a/website/source/docs/http/secret/cassandra/index.html.md b/website/source/docs/http/secret/cassandra/index.html.md new file mode 100644 index 000000000..a9f502ac5 --- /dev/null +++ b/website/source/docs/http/secret/cassandra/index.html.md @@ -0,0 +1,245 @@ +--- +layout: "http" +page_title: "Cassandra Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-cassandra" +description: |- + TODO +--- + +# Cassandra Secret Backend HTTP API + +This is the API documentation for the Vault Cassandra secret backend. For +general information about the usage and operation of the Cassandra backend, +please see the +[Vault Cassandra backend documentation](/docs/secrets/cassandra/index.html). + +This documentation assumes the Cassandra backend is mounted at the `/cassandra` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection information used to communicate with +Cassandra. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/cassandra/config/connection` | `204 (empty body)` | + +### Parameters + +- `hosts` `(string: )` – Specifies a set of comma-delineated Cassandra + hosts to connect to. + +- `username` `(string: )` – Specifies the username to use for + superuser access. + +- `password` `(string: )` – Specifies the password corresponding to + the given username. + +- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to + Cassandra. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the + server certificate when using TLS. + +- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a + certificate and private key; a certificate, private key, and issuing CA + certificate; or just a CA certificate. + +- `pem_json` `(string: "")` – Specifies JSON containing a certificate and + private key; a certificate, private key, and issuing CA certificate; or just a + CA certificate. For convenience format is the same as the output of the + `issue` command from the `pki` backend; see + [the pki documentation](/docs/secrets/pki/index.html). + +- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use. + +- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use. + +TLS works as follows: + +- If `tls` is set to true, the connection will use TLS; this happens + automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set + +- If `insecure_tls` is set to true, the connection will not perform verification + of the server certificate; this also sets `tls` to true + +- If only `issuing_ca` is set in `pem_json`, or the only certificate in + `pem_bundle` is a CA certificate, the given CA certificate will be used for + server certificate verification; otherwise the system CA certificates will be + used + +- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`, + client auth will be turned on for the connection + +`pem_bundle` should be a PEM-concatenated bundle of a private key + client +certificate, an issuing CA certificate, or both. `pem_json` should contain the +same information; for convenience, the JSON format is the same as that output by +the issue command from the PKI backend. + +### Sample Payload + +```json +{ + "hosts": "cassandra1.local", + "username": "user", + "password": "pass" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/cassandra/config/connection +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/cassandra/roles/:name` | `204 (empty body)` | + +### Parameters + +- `creation_cql` `(string: "")` – Specifies the CQL statements executed to + create and configure the new user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{username}}' and + '{{password}}' values will be substituted; it is required that these + parameters are in single quotes. The default creates a non-superuser user with + no authorization grants. + +- `rollback_cql` `(string: "")` – Specifies the CQL statements executed to + attempt a rollback if an error is encountered during user creation. The + default is to delete the user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{username}}' and + '{{password}}' values will be substituted; it is required that these + parameters are in single quotes. + +- `lease` `(string: "")` – Specifies the lease value provided as a string + duration with time suffix. "h" hour is the largest suffix. + +- `consistency` `(string: "Quorum")` – Specifies the consistency level value + provided as a string. Determines the consistency level used for operations + performed on the Cassandra database. + +### Sample Payload + +```json +{ + "creation_cql": "CREATE USER ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/cassandra/roles/my-role +``` + +
Returns
+
+ A `204` response code. +
+ + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/cassandra/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/cassandra/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "creation_cql": "CREATE USER...", + "rollback_cql": "DROP USER...", + "lease": "12h", + "consistency": "Quorum" + } +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/cassandra/roles/:name` | `204 (no body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/cassandra/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/cassandra/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \Z + https://vault.rocks/v1/cassandra/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "vault-root-1430158508-126", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/website/source/docs/http/secret/consul/index.html.md b/website/source/docs/http/secret/consul/index.html.md new file mode 100644 index 000000000..674c9fe20 --- /dev/null +++ b/website/source/docs/http/secret/consul/index.html.md @@ -0,0 +1,201 @@ +--- +layout: "http" +page_title: "Consul Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-consul" +description: |- + TODO +--- + +# Consul Secret Backend HTTP API + +This is the API documentation for the Vault Consul secret backend. For general +information about the usage and operation of the Consul backend, please see the +[Vault Consul backend documentation](/docs/secrets/consul/index.html). + +This documentation assumes the Consul backend is mounted at the `/consul` path +in Vault. Since it is possible to mount secret backends at any location, please +update your API calls accordingly. + +## Configure Access + +This endpoint configures the access information for Consul. This access +information is used so that Vault can communicate with Consul and generate +Consul tokens. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/consul/config/access` | `204 (empty body)` | + +### Parameters + +- `address` `(string: )` – Specifies the address of the Consul + instance, provided as `"host:port"` like `"127.0.0.1:8500"`. + +- `scheme` `(string: "http")` – Specifies the URL scheme to use. + +- `token` `(string: )` – Specifies the Consul ACL token to use. This + must be a management type token. + +### Sample Payload + +```json +{ + "address": "127.0.0.1:8500", + "scheme": "https", + "token": "adha..." +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + https://vault.rocks/v1/consul/config/access +``` + +## Create/Update Role + +This endpoint creates or updates the Consul role definition. If the role does +not exist, it will be created. If the role already exists, it will receive +updated attributes. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/consul/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Consul credential. This is part of the request URL. + +- `lease` `(string: "")` – Specifies the lease for this role. This is provided + as a string duration with a time suffix like `"30s"` or `"1h"`. If not + provided, the default Vault lease is used. + +- `policy` `(string: )` – Specifies the base64 encoded ACL policy. The + ACL format can be found in the [Consul ACL + documentation](https://www.consul.io/docs/internals/acl.html). This is + required unless the `token_type` is `management`. + +- `token_type` `(string: "client")` - Specifies the type of token to create when + using this role. Valid values are `"client"` or `"management"`. + +### Sample Payload + +To create management tokens: + +```json +{ + "token_type": "management" +} +``` + +To create a client token with a custom policy: + +```json +{ + "policy": "abd2...==" +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + https://vault.rocks/v1/consul/roles/example-role +``` + +## Read Role + +This endpoint queries for information about a Consul role with the given name. +If no role exists with that name, a 404 is returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/consul/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to query. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/consul/roles/example-role +``` + +### Sample Response + +```json +{ + "data": { + "policy": "abd2...==", + "lease": "1h0m0s", + "token_type": "client" + } +} +``` + +## Delete Role + +This endpoint deletes a Consul role with the given name. Even if the role does +not exist, this endpoint will still return a successful response. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/consul/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --request DELETE \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/consul/roles/example-role +``` + +## Generate Credential + +This endpoint generates a dynamic Consul token based on the given role +definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/consul/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Consul credential. This is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/consul/creds/example-role +``` + +### Sample Response + +```json +{ + "data": { + "token": "973a31ea-1ec4-c2de-0f63-623f477c2510" + } +} +``` diff --git a/website/source/docs/http/secret/cubbyhole/index.html.md b/website/source/docs/http/secret/cubbyhole/index.html.md new file mode 100644 index 000000000..77b31ca4e --- /dev/null +++ b/website/source/docs/http/secret/cubbyhole/index.html.md @@ -0,0 +1,155 @@ +--- +layout: "http" +page_title: "Cubbyhole Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-cubbyhole" +description: |- + TODO +--- + +# Cubbyhole Secret Backend HTTP API + +This is the API documentation for the Vault Cubbyhole secret backend. For +general information about the usage and operation of the Cubbyhole backend, +please see the +[Vault Cubbyhole backend documentation](/docs/secrets/cubbyhole/index.html). + +This documentation assumes the Cubbyhole backend is mounted at the `/cubbyhole` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Read Secret + +This endpoint retrieves the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/cubbyhole/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/cubbyhole/my-secret +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "foo": "bar" + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false +} +``` + +## List Secrets + +This endpoint returns a list of secret entries at the specified location. +Folders are suffixed with `/`. The input must be a folder; list on a file will +not return a value. The values themselves are not accessible via this command. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `List` | `/cubbyhole/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to list. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/cubbyhole/my-secret +``` + +### Sample Response + +The example below shows output for a query path of `cubbyhole/` when there are +secrets at `cubbyhole/foo` and `cubbyhole/foo/bar`; note the difference in the +two entries. + +```json +{ + "auth": null, + "data": { + "keys": ["foo", "foo/"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Create/Update Secret + +This endpoint stores a secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/cubbyhole/:path` | `204 (empty body)` | +| `PUT` | `/cubbyhole/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to + create/update. This is specified as part of the URL. + +- `:key` `(string: "")` – Specifies a key, paired with an associated value, to + be held at the given location. Multiple key/value pairs can be specified, and + all will be returned on a read operation. A key called `ttl` will trigger some + special behavior; see above for details. + +### Sample Payload + +```json +{ + "foo": "bar", + "zip": "zap" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/cubbyhole/my-secret +``` + +## Delete Secret + +This endpoint deletes the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/cubbyhole/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/cubbyhole/my-secret +``` diff --git a/website/source/docs/http/secret/generic/index.html.md b/website/source/docs/http/secret/generic/index.html.md new file mode 100644 index 000000000..6e1b33ea9 --- /dev/null +++ b/website/source/docs/http/secret/generic/index.html.md @@ -0,0 +1,159 @@ +--- +layout: "http" +page_title: "Generic Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-generic" +description: |- + TODO +--- + +# Generic Secret Backend HTTP API + +This is the API documentation for the Vault Generic secret backend. For general +information about the usage and operation of the Generic backend, please see +the [Vault Generic backend documentation](/docs/secrets/generic/index.html). + +This documentation assumes the Generic backend is mounted at the `/secret` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Read Secret + +This endpoint retrieves the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/secret/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/secret/my-secret +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "foo": "bar" + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## List Secrets + +This endpoint returns a list of key names at the specified location. Folders are +suffixed with `/`. The input must be a folder; list on a file will not return a +value. Note that no policy-based filtering is performed on keys; do not encode +sensitive information in key names. The values themselves are not accessible via +this command. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/secret/:path` | `200 application/json` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to list. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/secret/my-secret +``` + +### Sample Response + +The example below shows output for a query path of `secret/` when there are +secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two +entries. + +```json +{ + "auth": null, + "data": { + "keys": ["foo", "foo/"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Create/Update Secret + +This endpoint stores a secret at the specified location. If the value does not +yet exist, the calling token must have an ACL policy granting the `create` +capability. If the value already exists, the calling token must have an ACL +policy granting the `update` capability. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/secret/:path` | `204 (empty body)` | +| `PUT` | `/secret/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to + create/update. This is specified as part of the URL. + +- `:key` `(string: "")` – Specifies a key, paired with an associated value, to + be held at the given location. Multiple key/value pairs can be specified, and + all will be returned on a read operation. A key called `ttl` will trigger some + special behavior; see above for details. + +### Sample Payload + +```json +{ + "foo": "bar", + "zip": "zap" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/secret/my-secret +``` + +## Delete Secret + +This endpoint deletes the secret at the specified location. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/secret/:path` | `204 (empty body)` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/secret/my-secret +``` diff --git a/website/source/docs/http/secret/index.html.md b/website/source/docs/http/secret/index.html.md new file mode 100644 index 000000000..51dfc1531 --- /dev/null +++ b/website/source/docs/http/secret/index.html.md @@ -0,0 +1,19 @@ +--- +layout: "http" +page_title: "HTTP API" +sidebar_current: "docs-http-secret" +description: |- + Each secret backend publishes its own set of API paths and methods. These + endpoints are documented in this section. +--- + +# Secret Backends + +Each secret backend publishes its own set of API paths and methods. These +endpoints are documented in this section. Secret backends are mounted at a path, +but the documentation will assume the default mount points for simplicity. If +you are mounting at a different path, you should adjust your API calls +accordingly. + +For the API documentation for a specific secret backend, please choose a secret +backend from the navigation. diff --git a/website/source/docs/http/secret/mongodb/index.html.md b/website/source/docs/http/secret/mongodb/index.html.md new file mode 100644 index 000000000..4ddceee92 --- /dev/null +++ b/website/source/docs/http/secret/mongodb/index.html.md @@ -0,0 +1,344 @@ +--- +layout: "http" +page_title: "MongoDB Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-mongodb" +description: |- + TODO +--- + +# MongoDB Secret Backend HTTP API + +This is the API documentation for the Vault MongoDB secret backend. For general +information about the usage and operation of the MongoDB backend, please see +the [Vault MongoDB backend documentation](/docs/secrets/mongodb/index.html). + +This documentation assumes the MongoDB backend is mounted at the `/mongodb` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the standard connection string (URI) used to +communicate with MongoDB. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mongodb/config/connection` | `200 application/json` | + +### Parameters + +- `url` `(string: )` – Specifies the MongoDB standard connection + string (URI). + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. + +### Sample Payload + +```json +{ + "url": "mongodb://db1.example.net,db2.example.net:2500/?replicaSet=test" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mongodb/config/connection +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "wrap_info": null, + "warnings": [ + "Read access to this endpoint should be controlled via ACLs as it will return the connection URI as it is, including passwords, if any." + ], + "auth": null +} +``` + +## Read Connection + +This endpoint queries the connection configuration. Access to this endpoint +should be controlled via ACLs as it will return the connection URI as it is, +including passwords, if any. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/config/connection` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/config/connection +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "uri": "mongodb://admin:Password!@mongodb.acme.com:27017/admin?ssl=true" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Configure Lease + +This endpoint configures the default lease TTL settings for credentials +generated by the mongodb backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mongodb/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mongodb/config/lease +``` + +## Read Lease + +This endpoint queries the lease configuration. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/config/lease` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/config/lease +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "max_ttl": 60, + "ttl": 60 + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Create Role + +This endpoint creates or updates a role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mongodb/roles/:name` | `204 (empty body)` | + +### Parameters + +- `db` `(string: )` – Specifies the name of the database users should + be created in for this role. + +- `roles` `(string: "")` – Specifies the MongoDB roles to assign to the users + generated for this role. + +### Sample Payload + +```json +{ + "db": "my-db", + "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mongodb/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/roles/my-role +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "db": "foo", + "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/mongodb/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/mongodb/roles +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "keys": [ + "dev", + "prod" + ] + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/mongodb/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/mongodb/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mongodb/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mongodb/creds/my-role +``` + +### Sample Response + +```json +{ + "lease_id": "mongodb/creds/readonly/e64e79d8-9f56-e379-a7c5-373f9b4ee3d8", + "renewable": true, + "lease_duration": 3600, + "data": { + "db": "foo", + "password": "de0f7b50-d700-54e5-4e81-5c3724283999", + "username": "vault-token-b32098cb-7ff2-dcf5-83cd-d5887cedf81b" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` diff --git a/website/source/docs/http/secret/mssql/index.html.md b/website/source/docs/http/secret/mssql/index.html.md new file mode 100644 index 000000000..6099ff027 --- /dev/null +++ b/website/source/docs/http/secret/mssql/index.html.md @@ -0,0 +1,244 @@ +--- +layout: "http" +page_title: "MSSQL Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-mssql" +description: |- + TODO +--- + +# MSSQL Secret Backend HTTP API + +This is the API documentation for the Vault MSSQL secret backend. For general +information about the usage and operation of the MSSQL backend, please see +the [Vault MSSQL backend documentation](/docs/secrets/mssql/index.html). + +This documentation assumes the MSSQL backend is mounted at the `/mssql` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection DSN used to communicate with Microsoft +SQL Server. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mssql/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_string` `(string: )` – Specifies the MSSQL DSN. + +- `max_open_connections` `(int: 2)` – Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` – Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +### Sample Payload + +```json +{ + "connection_string": "Server=myServerAddress;Database=myDataBase;User Id=myUsername; Password=myPassword;" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mssql/config/connection +``` + +## Configure Lease + +This endpoint configures the lease settings for generated credentials. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mssql/config/lease +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mssql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `sql` `(string: )` – Specifies the SQL statements executed to create + and configure the role. The '{{name}}' and '{{password}}' values will be + substituted. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. + +### Sample Payload + +```json +{ + "sql": "CREATE LOGIN ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mssql/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mssql/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mssql/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "sql": "CREATE LOGIN..." + } +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/mssql/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/mssql/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/mssql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/mssql/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mssql/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mssql/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "root-a147d529-e7d6-4a16-8930-4c3e72170b19", + "password": "ee202d0d-e4fd-4410-8d14-2a78c5c8cb76" + } +} +``` diff --git a/website/source/docs/http/secret/mysql/index.html.md b/website/source/docs/http/secret/mysql/index.html.md new file mode 100644 index 000000000..c543ddb03 --- /dev/null +++ b/website/source/docs/http/secret/mysql/index.html.md @@ -0,0 +1,265 @@ +--- +layout: "http" +page_title: "MySQL Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-mysql" +description: |- + TODO +--- + +# MySQL Secret Backend HTTP API + +This is the API documentation for the Vault MySQL secret backend. For general +information about the usage and operation of the MySQL backend, please see +the [Vault MySQL backend documentation](/docs/secrets/mysql/index.html). + +This documentation assumes the MySQL backend is mounted at the `/mysql` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection DSN used to communicate with MySQL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_url` `(string: )` – Specifies the MySQL DSN. + +- `max_open_connections` `(int: 2)` – Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` – Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. + +### Sample Payload + +```json +{ + "connection_url": "mysql:host=localhost;dbname=testdb" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mysql/config/connection +``` + +## Configure Lease + +This endpoint configures the lease settings for generated credentials. If not +configured, leases default to 1 hour. This is a root protected endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mysql/config/lease +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/mysql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `sql` `(string: )` – Specifies the SQL statements executed to create + and configure a user. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' and + '{{password}}' values will be substituted. + +- `revocation_sql` `(string: "")` – Specifies the SQL statements executed to + revoke a user. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' value will be + substituted. + +- `rolename_length` `(int: 4)` – Specifies how many characters from the role + name will be used to form the mysql username interpolated into the '{{name}}' + field of the sql parameter. + +- `displayname_length` `(int: 4)` – Specifies how many characters from the token + display name will be used to form the mysql username interpolated into the + '{{name}}' field of the sql parameter. + +- `username_length` `(int: 16)` – Specifies the maximum total length in + characters of the mysql username interpolated into the '{{name}}' field of the + sql parameter. + +### Sample Payload + +```json +{ + "sql": "CREATE USER ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/mysql/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mysql/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mysql/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "sql": "CREATE USER..." + } +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/mysql/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/mysql/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/mysql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/mysql/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/mysql/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/mysql/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "user-role-aefa63", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/website/source/docs/http/secret/pki/index.html.md b/website/source/docs/http/secret/pki/index.html.md new file mode 100644 index 000000000..df9ae26f4 --- /dev/null +++ b/website/source/docs/http/secret/pki/index.html.md @@ -0,0 +1,1456 @@ +--- +layout: "http" +page_title: "PKI Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-pki" +description: |- + TODO +--- + +# PKI Secret Backend HTTP API + +This is the API documentation for the Vault PKI secret backend. For general +information about the usage and operation of the PKI backend, please see the +[Vault PKI backend documentation](/docs/secrets/pki/index.html). + +This documentation assumes the PKI backend is mounted at the `/pki` path in +Vault. Since it is possible to mount secret backends at any location, please +update your API calls accordingly. + + +### /pki/ca(/pem) +#### GET + +
+
Description
+
+ Retrieves the CA certificate *in raw DER-encoded form*. This is a bare + endpoint that does not return a standard Vault data structure. If `/pem` is + added to the endpoint, the CA certificate is returned in PEM format.
+
This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/ca(/pem)`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ``` + + ``` + +
+
+ +### /pki/ca_chain +#### GET + +
+
Description
+
+ Retrieves the CA certificate chain, including the CA *in PEM format*. This + is a bare endpoint that does not return a standard Vault data structure. +

This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/ca_chain`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ``` + + ``` + +
+
+ +### /pki/cert/ +#### GET + +
+
Description
+
+ Retrieves one of a selection of certificates. Valid values: `ca` for the CA + certificate, `crl` for the current CRL, `ca_chain` for the CA trust chain + or a serial number in either hyphen-separated or colon-separated octal + format. This endpoint returns the certificate in PEM formatting in the + `certificate` key of the JSON object.

This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/cert/`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n..." + } + } + ... + ``` + +
+
+ +### /pki/certs/ +#### LIST + +
+
Description
+
+ Returns a list of the current certificates by serial number only. +
+ +
Method
+
LIST/GET
+ +
URL
+
`/pki/certs` (LIST) or `/pki/certs?list=true` (GET)
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "lease_id":"", + "renewable":false, + "lease_duration":0, + "data":{ + "keys":[ + "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1", + "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21" + ] + }, + "wrap_info":null, + "warnings":null, + "auth":null + } + ... + ``` + +
+
+ +### /pki/config/ca +#### POST + +
+
Description
+
+ Allows submitting the CA information for the backend via a PEM file + containing the CA certificate and its private key, concatenated. Not needed + if you are generating a self-signed root certificate, and not used if you + have a signed intermediate CA certificate with a generated key (use the + `/pki/intermediate/set-signed` endpoint for that). _If you have already set + a certificate and key, they will be overridden._

The information + can be provided from a file via a `curl` command similar to the + following:
+ + ```text + $ curl \ + -H "X-Vault-Token:06b9d..." \ + -X POST \ + --data "@cabundle.json" \ + http://127.0.0.1:8200/v1/pki/config/ca + ``` + + Note that if you provide the data through the HTTP API it must be + JSON-formatted, with newlines replaced with `\n`, like so: + + ```javascript + { + "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" + } + ``` +
+ +
Method
+
POST
+ +
URL
+
`/pki/config/ca`
+ +
Parameters
+
+
    +
  • + pem_bundle + required + The key and certificate concatenated in PEM format. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/config/crl +#### GET + +
+
Description
+
+ Allows getting the duration for which the generated CRL should be marked + valid. +
+ +
Method
+
GET
+ +
URL
+
`/pki/config/crl`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "expiry": "72h" + }, + "auth": null + } + ``` + +
+
+ +#### POST + +
+
Description
+
+ Allows setting the duration for which the generated CRL should be marked + valid. +
+ +
Method
+
POST
+ +
URL
+
`/pki/config/crl`
+ +
Parameters
+
+
    +
  • +
  • + expiry + required + The time until expiration. Defaults to `72h`. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/config/urls + +#### GET + +
+
Description
+
+ Fetch the URLs to be encoded in generated certificates. +
+ +
Method
+
GET
+ +
URL
+
`/pki/config/urls`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "issuing_certificates": [, ], + "crl_distribution_points": [, ], + "ocsp_servers": [, ], + }, + "auth": null + } + ``` + +
+
+ +#### POST + +
+
Description
+
+ Allows setting the issuing certificate endpoints, CRL distribution points, + and OCSP server endpoints that will be encoded into issued certificates. + You can update any of the values at any time without affecting the other + existing values. To remove the values, simply use a blank string as the + parameter. +
+ +
Method
+
POST
+ +
URL
+
`/pki/config/urls`
+ +
Parameters
+
+
    +
  • + issuing_certificates + optional + The URL values for the Issuing Certificate field. +
    • +
  • + crl_distribution_points + optional + The URL values for the CRL Distribution Points field. +
    • +
  • + ocsp_servers + optional + The URL values for the OCSP Servers field. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/crl(/pem) +#### GET + +
+
Description
+
+ Retrieves the current CRL *in raw DER-encoded form*. This endpoint + is suitable for usage in the CRL Distribution Points extension in a + CA certificate. This is a bare endpoint that does not return a + standard Vault data structure. If `/pem` is added to the endpoint, + the CRL is returned in PEM format. +

This is an unauthenticated endpoint. +
+ +
Method
+
GET
+ +
URL
+
`/pki/crl(/pem)`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ``` + + ``` + +
+
+ +### /pki/crl/rotate +#### GET + +
+
Description
+
+ This endpoint forces a rotation of the CRL. This can be used + by administrators to cut the size of the CRL if it contains + a number of certificates that have now expired, but has + not been rotated due to no further certificates being revoked. +
+ +
Method
+
GET
+ +
URL
+
`/pki/crl/rotate`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "data": { + "success": true + } + } + ``` + +
+
+ +### /pki/intermediate/generate +#### POST + +
+
Description
+
+ Generates a new private key and a CSR for signing. If using Vault as a + root, and for many other CAs, the various parameters on the final + certificate are set at signing time and may or may not honor the parameters + set here. _This will overwrite any previously existing CA private key._ If + the path ends with `exported`, the private key will be returned in the + response; if it is `internal` the private key will not be returned and + *cannot be retrieved later*.

This is mostly meant as a helper + function, and not all possible parameters that can be set in a CSR are + supported. +
+ +
Method
+
POST
+ +
URL
+
`/pki/intermediate/generate/[exported|internal]`
+ +
Parameters
+
+
    +
  • + common_name + required + The requested CN for the certificate. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `csr` field will contain the private key (if + exported) and CSR, concatenated. +
    • +
  • + key_type + optional + Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. +
    • +
  • + key_bits + optional + The number of bits to use. Defaults to `2048`. Must be changed to a + valid value if the `key_type` is `ec`. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 21600, + "data": { + "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n", + "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----", + "private_key_type": "rsa" + }, + "warnings": null, + "auth": null + } + ``` + +
+
+ +### /pki/intermediate/set-signed +#### POST + +
+
Description
+
+ Allows submitting the signed CA certificate corresponding to a private key generated via `/pki/intermediate/generate`. The certificate should be submitted in PEM format; see the documentation for `/pki/config/ca` for some hints on submitting. +
+ +
Method
+
POST
+ +
URL
+
`/pki/intermediate/set-signed`
+ +
Parameters
+
+
    +
  • + certificate + required + The certificate in PEM format. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/issue/ +#### POST + +
+
Description
+
+ Generates a new set of credentials (private key and certificate) based on + the role named in the endpoint. The issuing CA certificate is returned as + well, so that only the root CA need be in a client's trust store.

*The private key is _not_ stored. If you do not save the private + key, you will need to request a new certificate.* +
+ +
Method
+
POST
+ +
URL
+
`/pki/issue/`
+ +
Parameters
+
+
    +
  • + common_name + required + The requested CN for the certificate. If the CN is allowed by role + policy, it will be issued. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. If any requested names do not match role policy, the + entire request will be denied. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. Only + valid if the role allows IP SANs (which is the default). +
    • +
  • + ttl + optional + Requested Time To Live. Cannot be greater than the role's `max_ttl` + value. If not provided, the role's `ttl` value will be used. Note that + the role values default to system values if not explicitly set. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the private key and + certificate, concatenated; if the issuing CA is not a Vault-derived + self-signed root, this will be included as well. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n", + "private_key_type": "rsa", + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "warnings": "", + "auth": null + } + ``` + +
+
+ +### /pki/revoke +#### POST + +
+
Description
+
+ Revokes a certificate using its serial number. This is an + alternative option to the standard method of revoking + using Vault lease IDs. A successful revocation will + rotate the CRL. +
+ +
Method
+
POST
+ +
URL
+
`/pki/revoke`
+ +
Parameters
+
+
    +
  • + serial_number + required + The serial number of the certificate to revoke, in + hyphen-separated or colon-separated octal. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "data": { + "revocation_time": 1433269787 + } + } + ``` +
+
+ +### /pki/roles/ +#### POST + +
+
Description
+
+ Creates or updates the role definition. Note that the + `allowed_domains`, `allow_subdomains`, and + `allow_any_name` attributes are additive; between them nearly and across + multiple roles nearly any issuing policy can be accommodated. + `server_flag`, `client_flag`, and `code_signing_flag` are additive as well. + If a client requests a certificate that is not allowed by the CN policy in + the role, the request is denied. +
+ +
Method
+
POST
+ +
URL
+
`/pki/roles/`
+ +
Parameters
+
+
    +
  • + ttl + optional + The Time To Live value provided as a string duration with time suffix. + Hour is the largest suffix. If not set, uses the system default value + or the value of `max_ttl`, whichever is shorter. +
    • +
  • + max_ttl + optional + The maximum Time To Live provided as a string duration with time + suffix. Hour is the largest suffix. If not set, defaults to the system + maximum lease TTL. +
    • +
  • + allow_localhost + optional + If set, clients can request certificates for `localhost` as one of the + requested common names. This is useful for testing and to allow clients + on a single host to talk securely. Defaults to true. +
    • +
  • + allowed_domains + optional + Designates the domains of the role, provided as a comma-separated list. + This is used with the `allow_bare_domains` and `allow_subdomains` + options. There is no default. +
    • +
  • + allow_bare_domains + optional + If set, clients can request certificates matching the value of the + actual domains themselves; e.g. if a configured domain set with + `allowed_domains` is `example.com`, this allows clients to actually + request a certificate containing the name `example.com` as one of the + DNS values on the final certificate. In some scenarios, this can be + considered a security risk. Defaults to false. +
    • +
  • + allow_subdomains + optional + If set, clients can request certificates with CNs that are subdomains + of the CNs allowed by the other role options. _This includes wildcard + subdomains._ For example, an `allowed_domains` value of + `example.com` with this option set to true will allow `foo.example.com` + and `bar.example.com` as well as `*.example.com`. This is redundant + when using the `allow_any_name` option. Defaults to `false`. +
    • +
  • + allow_any_name + optional + If set, clients can request any CN. Useful in some circumstances, but + make sure you understand whether it is appropriate for your + installation before enabling it. Defaults to `false`. +
    • +
  • + enforce_hostnames + optional + If set, only valid host names are allowed for CNs, DNS SANs, and the + host part of email addresses. Defaults to `true`. +
    • +
  • + allow_ip_sans + optional + If set, clients can request IP Subject Alternative Names. No + authorization checking is performed except to verify that the given + values are valid IP addresses. Defaults to `true`. +
  • + server_flag + optional + If set, certificates are flagged for server use. Defaults to `true`. +
    • +
  • + client_flag + optional + If set, certificates are flagged for client use. Defaults to `true`. +
    • +
  • + code_signing_flag + optional + If set, certificates are flagged for code signing use. Defaults to + `false`. +
    • +
  • + email_protection_flag + optional + If set, certificates are flagged for email protection use. Defaults to + `false`. +
    • +
  • + key_type + optional + The type of key to generate for generated private + keys. Currently, `rsa` and `ec` are supported. + Defaults to `rsa`. +
    • +
  • + key_bits + optional + The number of bits to use for the generated keys. + Defaults to `2048`; this will need to be changed for + `ec` keys. See https://golang.org/pkg/crypto/elliptic/#Curve + for an overview of allowed bit lengths for `ec`. +
    • +
  • + key_usage + optional + This sets the allowed key usage constraint on issued certificates. This + is a comma-separated string; valid values can be found at + https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the + `KeyUsage` part of the value. Values are not case-sensitive. To specify + no key usage constraints, set this to an empty string. Defaults to + `DigitalSignature,KeyAgreement,KeyEncipherment`. +
    • +
  • + use_csr_common_name + optional + If set, when used with the CSR signing endpoint, the common name in the + CSR will be used instead of taken from the JSON data. This does `not` + include any requested SANs in the CSR; use `use_csr_sans` for that. + Defaults to `true`. +
    • +
  • + use_csr_sans + optional + If set, when used with the CSR signing endpoint, the subject alternate + names in the CSR will be used instead of taken from the JSON data. This + does `not` include the common name in the CSR; use + `use_csr_common_name` for that. Defaults to `true`. +
    • +
  • + allow_token_displayname + optional + If set, the display name of the token used when requesting a + certificate will be considered to be a valid host name by the role. + Normal verification behavior applies with respect to subdomains and + wildcards. +
    • +
  • + ou + optional + This sets the OU (OrganizationalUnit) values in the subject field of + issued certificates. This is a comma-separated string. +
    • +
  • + organization + optional + This sets the O (Organization) values in the subject field of issued + certificates. This is a comma-separated string. +
    • +
  • + generate_lease + optional + If set, certificates issued/signed against this role will have Vault + leases attached to them. Defaults to "false". Certificates can be added + to the CRL by `vault revoke ` when certificates are + associated with leases. It can also be done using the `pki/revoke` + endpoint. However, when lease generation is disabled, invoking + `pki/revoke` would be the only way to add the certificates to the CRL. + When large number of certificates are generated with long lifetimes, it + is recommended that lease generation be disabled, as large amount of + leases adversely affect the startup time of Vault. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+
+ +#### GET + +
+
Description
+
+ Queries the role definition. +
+ +
Method
+
GET
+ +
URL
+
`/pki/roles/`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "data": { + "allow_any_name": false, + "allow_ip_sans": true, + "allow_localhost": true, + "allow_subdomains": false, + "allowed_domains": "example.com,foobar.com", + "client_flag": true, + "code_signing_flag": false, + "key_bits": 2048, + "key_type": "rsa", + "ttl": "6h", + "max_ttl": "12h", + "server_flag": true + } + } + ``` + +
+
+ +#### LIST + +
+
Description
+
+ Returns a list of available roles. Only the role names are returned, not + any values. +
+ +
Method
+
LIST/GET
+ +
URL
+
`/pki/roles` (LIST) or `/pki/roles?list=true` (GET)
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```javascript + { + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false + } + ``` + +
+
+ +#### DELETE + +
+
Description
+
+ Deletes the role definition. Deleting a role does not revoke + certificates previously issued under this role. +
+ +
Method
+
DELETE
+ +
URL
+
`/pki/roles/`
+ +
Parameters
+
+ None +
+ +
Returns
+
+ A `204` response code. +
+
+ +### /pki/root/generate +#### POST + +
+
Description
+
+ Generates a new self-signed CA certificate and private key. _This will + overwrite any previously-existing private key and certificate._ If the path + ends with `exported`, the private key will be returned in the response; if + it is `internal` the private key will not be returned and *cannot be + retrieved later*. Distribution points use the values set via `config/urls`. +

As with other issued certificates, Vault will automatically + revoke the generated root at the end of its lease period; the CA + certificate will sign its own CRL. +
+ +
Method
+
POST
+ +
URL
+
`/pki/root/generate/[exported|internal]`
+ +
Parameters
+
+
    +
  • + common_name + required + The requested CN for the certificate. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. +
    • +
  • + ttl + optional + Requested Time To Live (after which the certificate will be expired). + This cannot be larger than the mount max (or, if not set, the system + max). +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the private key (if + exported) and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. +
    • +
  • + key_type + optional + Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. +
    • +
  • + key_bits + optional + The number of bits to use. Defaults to `2048`. Must be changed to a + valid value if the `key_type` is `ec`. +
    • +
  • + max_path_length + optional + If set, the maximum path length to encode in the generated certificate. + Defaults to `-1`, which means no limit. unless the signing certificate + has a maximum path length set, in which case the path length is set to + one less than that of the signing certificate. A limit of `0` means a + literal path length of zero. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/root/sign-intermediate +#### POST + +
+
Description
+
+ Uses the configured CA certificate to issue a certificate with appropriate + values for acting as an intermediate CA. Distribution points use the values + set via `config/urls`. Values set in the CSR are ignored unless + `use_csr_values` is set to true, in which case the values from the CSR are + used verbatim. +
+ +
Method
+
POST
+ +
URL
+
`/pki/root/sign-intermediate`
+ +
Parameters
+
+
    +
  • + csr + required + The PEM-encoded CSR. +
    • +
  • + common_name + required + The requested CN for the certificate. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. +
    • +
  • + ttl + optional + Requested Time To Live (after which the certificate will be expired). + This cannot be larger than the mount max (or, if not set, the system + max). +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, + if the issuing CA is not a Vault-derived self-signed root, it will be + concatenated with the certificate. +
    • +
  • + max_path_length + optional + If set, the maximum path length to encode in the generated certificate. + Defaults to `-1`, which means no limit. unless the signing certificate + has a maximum path length set, in which case the path length is set to + one less than that of the signing certificate. A limit of `0` means a + literal path length of zero. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
  • + use_csr_values + optional + If set to `true`, then: 1) Subject information, including names and + alternate names, will be preserved from the CSR rather than using the + values provided in the other parameters to this path; 2) Any key usages + (for instance, non-repudiation) requested in the CSR will be added to + the basic set of key usages used for CA certs signed by this path; 3) + Extensions requested in the CSR will be copied into the issued + certificate. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/sign/ +#### POST + +
+
Description
+
+ Signs a new certificate based upon the provided CSR and the supplied + parameters, subject to the restrictions contained in the role named in the + endpoint. The issuing CA certificate is returned as well, so that only the + root CA need be in a client's trust store. +
+ +
Method
+
POST
+ +
URL
+
`/pki/sign/`
+ +
Parameters
+
+
    +
  • + csr + required + The PEM-encoded CSR. +
    • +
  • + common_name + required + The requested CN for the certificate. If the CN is allowed by role + policy, it will be issued. +
    • +
  • + alt_names + optional + Requested Subject Alternative Names, in a comma-delimited list. These + can be host names or email addresses; they will be parsed into their + respective fields. If any requested names do not match role policy, the + entire request will be denied. +
    • +
  • + ip_sans + optional + Requested IP Subject Alternative Names, in a comma-delimited list. Only + valid if the role allows IP SANs (which is the default). +
    • +
  • + ttl + optional + Requested Time To Live. Cannot be greater than the role's `max_ttl` + value. If not provided, the role's `ttl` value will be used. Note that + the role values default to system values if not explicitly set. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, + if the issuing CA is not a Vault-derived self-signed root, it will be + concatenated with the certificate. +
    • +
  • + exclude_cn_from_sans + optional + If set, the given `common_name` will not be included in DNS or Email + Subject Alternate Names (as appropriate). Useful if the CN is not a + hostname or email address, but is instead some human-readable + identifier. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/sign-verbatim +#### POST + +
+
Description
+
+ Signs a new certificate based upon the provided CSR. Values are taken + verbatim from the CSR; the _only_ restriction is that this endpoint will + refuse to issue an intermediate CA certificate (see the + `/pki/root/sign-intermediate` endpoint for that functionality.) _This is a + potentially dangerous endpoint and only highly trusted users should + have access._ +
+ +
Method
+
POST
+ +
URL
+
`/pki/sign-verbatim`
+ +
Parameters
+
+
    +
  • + csr + required + The PEM-encoded CSR. +
    • +
  • + ttl + optional + Requested Time To Live. Cannot be greater than the mount's `max_ttl` + value. If not provided, the mount's `ttl` value will be used, which + defaults to system values if not explicitly set. +
    • +
  • + format + optional + Format for returned data. Can be `pem`, `der`, or `pem_bundle`; + defaults to `pem`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, + if the issuing CA is not a Vault-derived self-signed root, it will be + concatenated with the certificate. +
    • +
+
+ +
Returns
+
+ + ```javascript + { + "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"] + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null + } + ``` + +
+
+ +### /pki/tidy +#### POST + +
+
Description
+
+ Allows tidying up the backend storage and/or CRL by removing certificates + that have expired and are past a certain buffer period beyond their + expiration time. +
+ +
Method
+
POST
+ +
URL
+
`/pki/tidy`
+ +
Parameters
+
+
    +
  • + tidy_cert_store + optional + Whether to tidy up the certificate store. Defaults to `false`. +
    • +
  • + tidy_revocation_list + optional + Whether to tidy up the revocation list (CRL). Defaults to `false`. +
    • +
  • + safety_buffer + optional + A duration (given as an integer number of seconds or a string; defaults + to `72h`) used as a safety buffer to ensure certificates are not + expunged prematurely; as an example, this can keep certificates from + being removed from the CRL that, due to clock skew, might still be + considered valid on other hosts. For a certificate to be expunged, the + time must be after the expiration time of the certificate (according to + the local clock) plus the duration of `safety_buffer`. +
    • +
+
+ +
Returns
+
+ A `204` status code. +
+
+======= +The PKI secret backend has a full HTTP API. Please see the +[PKI secret backend API](/docs/http/secret/pki/index.html) for more +details. +>>>>>>> e54ffcd1... Break out API documentation for secret backends diff --git a/website/source/docs/http/secret/postgresql/index.html.md b/website/source/docs/http/secret/postgresql/index.html.md new file mode 100644 index 000000000..6b032f6b1 --- /dev/null +++ b/website/source/docs/http/secret/postgresql/index.html.md @@ -0,0 +1,259 @@ +--- +layout: "http" +page_title: "PostgreSQL Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-postgresql" +description: |- + TODO +--- + +# PostgreSQL Secret Backend HTTP API + +This is the API documentation for the Vault PostgreSQL secret backend. For +general information about the usage and operation of the PostgreSQL backend, +please see the +[Vault PostgreSQL backend documentation](/docs/secrets/postgresql/index.html). + +This documentation assumes the PostgreSQL backend is mounted at the +`/postgresql` path in Vault. Since it is possible to mount secret backends at +any location, please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection string used to communicate with +PostgreSQL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/postgresql/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_url` `(string: )` – Specifies the PostgreSQL connection + URL or PG-style string, for example `"user=foo host=bar"`. + +- `max_open_connections` `(int: 2)` – Specifies the maximum number of open + connections to the database. A negative value means unlimited. + +- `max_idle_connections` `(int: 0)` – Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If this is larger than + `max_open_connections` it will be reduced to be equal. + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. + +### Sample Payload + +```json +{ + "connection_url": "postgresql://user:pass@localhost/my-db" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/postgresql/config/connection +``` + +## Configure Lease + +This configures the lease settings for generated credentials. If not configured, +leases default to 1 hour. This is a root protected endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/postgresql/config/lease` | `204 (empty body)` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample Payload + +```json +{ + "lease": "12h", + "lease_max": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/postgresql/config/lease +``` + +## Create Role + +This endpoint creates or updates a role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/postgresql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is specified as part of the URL. + +- `sql` `(string: )` – Specifies the SQL statements executed to create + and configure the role. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}', '{{password}}' + and '{{expiration}}' values will be substituted. + +- `revocation_sql` `(string: "")` – Specifies the SQL statements to be executed + to revoke a user. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The '{{name}}' value will be + substituted. + +### Sample Payload + +```json +{ + "sql": "CREATE USER WITH ROLE {{name}}" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/postgresql/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/postgresql/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/postgresql/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "sql": "CREATE USER..." + } +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/postgresql/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/postgresql/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/postgresql/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/postgresql/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/postgresql/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/postgresql/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "root-1430158508-126", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/website/source/docs/http/secret/rabbitmq/index.html.md b/website/source/docs/http/secret/rabbitmq/index.html.md new file mode 100644 index 000000000..bf642f911 --- /dev/null +++ b/website/source/docs/http/secret/rabbitmq/index.html.md @@ -0,0 +1,218 @@ +--- +layout: "http" +page_title: "RabbitMQ Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-rabbitmq" +description: |- + TODO +--- + +# RabbitMQ Secret Backend HTTP API + +This is the API documentation for the Vault RabbitMQ secret backend. For general +information about the usage and operation of the RabbitMQ backend, please see +the [Vault RabbitMQ backend documentation](/docs/secrets/rabbitmq/index.html). + +This documentation assumes the RabbitMQ backend is mounted at the `/rabbitmq` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Configure Connection + +This endpoint configures the connection string used to communicate with +RabbitMQ. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/rabbitmq/config/connection` | `204 (empty body)` | + +### Parameters + +- `connection_uri` `(string: )` – Specifies the RabbitMQ connection + URI. + +- `username` `(string: )` – Specifies the RabbitMQ management + administrator username. + +- `password` `(string: )` – Specifies the RabbitMQ management + administrator password. + +- `verify_connection` `(bool: true)` – Specifies whether to verify connection + URI, username, and password. + +### Sample Payload + +```json +{ + "connection_uri": "https://...", + "username": "user", + "password": "password" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/rabbitmq/config/connection +``` + +## Configure Lease + +This endpoint configures the lease settings for generated credentials. This is +endpoint requires sudo privileges. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/rabbitmq/config/lease` | `204 (empty body)` | + +### Parameters + +- `ttl` `(int: 0)` – Specifies the lease ttl provided in seconds. + +- `max_ttl` `(int: 0)` – Specifies the maximum ttl provided in seconds. + +### Sample Payload + +```json +{ + "ttl": 1800, + "max_ttl": 3600 +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/rabbitmq/config/lease +``` + +## Create Role + +This endpoint creates or updates the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/rabbitmq/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is specified as part of the URL. + +- `tags` `(string: "")` – Specifies a comma-separated RabbitMQ management tags. + +- `vhost` `(string: "")` – Specifies a map of virtual hosts to + permissions. + +### Sample Payload + +```json +{ + "tags": "tag1,tag2", + "vhost": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/rabbitmq/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/rabbitmq/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/rabbitmq/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "tags": "", + "vhost": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}" + } +} +``` + +## Delete Role + +This endpoint deletes the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/rabbitmq/roles/:namer` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/rabbitmq/roles/my-role +``` + +## Generate Credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/rabbitmq/creds/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/rabbitmq/creds/my-role +``` + +### Sample Response + +```json +{ + "data": { + "username": "root-4b95bf47-281d-dcb5-8a60-9594f8056092", + "password": "e1b6c159-ca63-4c6a-3886-6639eae06c30" + } +} +``` diff --git a/website/source/docs/http/secret/ssh/index.html.md b/website/source/docs/http/secret/ssh/index.html.md new file mode 100644 index 000000000..df530de10 --- /dev/null +++ b/website/source/docs/http/secret/ssh/index.html.md @@ -0,0 +1,861 @@ +--- +layout: "http" +page_title: "SSH Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-ssh" +description: |- + TODO +--- + +# SSH Secret Backend HTTP API + +This is the API documentation for the Vault SSH secret backend. For general +information about the usage and operation of the SSH backend, please see the +[Vault SSH backend documentation](/docs/secrets/ssh/index.html). + +This documentation assumes the SSH backend is mounted at the `/ssh` path in +Vault. Since it is possible to mount secret backends at any location, please +update your API calls accordingly. + +### /ssh/keys/ +#### POST + +
+
Description
+
+ Creates or updates a named key. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/keys/`
+ +
Parameters
+
+
    +
  • + key + required + (String) + SSH private key with appropriate privileges on remote hosts. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+ +#### DELETE + +
+
Description
+
+ Deletes a named key. +
+ +
Method
+
DELETE
+ +
URL
+
`/ssh/keys/`
+ +
Parameters
+
None
+ +
Returns
+
+ A `204` response code. +
+ +### /ssh/roles/ +#### POST + +
+
Description
+
+ Creates or updates a named role. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/roles/`
+ +
Parameters
+
+
    +
  • + key + required for Dynamic Key type, N/A for + OTP type, N/A for CA type + (String) + Name of the registered key in Vault. Before creating the role, use + the `keys/` endpoint to create a named key. +
    • +
  • + admin_user + required for Dynamic Key type, N/A for OTP + type, N/A for CA type + (String) + Admin user at remote host. The shared key being registered should be + for this user and should have root or sudo privileges. Every time a + dynamic credential is generated for a client, Vault uses this admin + username to login to remote host and install the generated + credential. +
    • +
  • + default_user + required for Dynamic Key type, required + for OTP type, optional for CA type + (String) + Default username for which a credential will be generated. When the + endpoint 'creds/' is used without a username, this value will be used + as default username. Its recommended to create individual roles for + each username to ensure absolute isolation between usernames. + + For the CA type, if you wish this to be a valid principal, it must + also be in `allowed_users`. +
    • +
  • + cidr_list + optional for Dynamic Key type, optional for + OTP type, N/A for CA type + (String) + Comma separated list of CIDR blocks for which the role is applicable + for. CIDR blocks can belong to more than one role. +
    • +
  • + exclude_cidr_list + optional for Dynamic Key type, optional for + OTP type, N/A for CA type + (String) + Comma-separated list of CIDR blocks. IP addresses belonging to these + blocks are not accepted by the role. This is particularly useful when + big CIDR blocks are being used by the role and certain parts need to + be kept out. +
    • +
  • + port + optional for Dynamic Key type, optional for + OTP type, N/A for CA type + (Integer) + Port number for SSH connection. The default is '22'. Port number + does not play any role in OTP generation. For the 'otp' backend + type, this is just a way to inform the client about the port number + to use. The port number will be returned to the client by Vault + along with the OTP. +
    • +
  • + key_type + required for all types + (String) + Type of credentials generated by this role. Can be either `otp`, + `dynamic` or `ca`. +
    • +
  • + key_bits + optional for Dynamic Key type, N/A for OTP type, + N/A for CA type + (Integer) + Length of the RSA dynamic key in bits; can be either 1024 or 2048. + 1024 the default. +
    • +
  • + install_script + optional for Dynamic Key type, N/A for OTP type, + N/A for CA type + (String) + Script used to install and uninstall public keys in the target + machine. Defaults to the built-in script. +
    • +
  • + allowed_users + optional for all types + (String) + If this option is not specified, client can request for a credential + for any valid user at the remote host, including the admin user. If + only certain usernames are to be allowed, then this list enforces it. + If this field is set, then credentials can only be created for + `default_user` and usernames present in this list. Setting this + option will enable all the users with access this role to fetch + credentials for all other usernames in this list. Use with caution. +
    • +
  • + allowed_domains + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + (String) + If this option is not specified, client can request for a signed certificate for any + valid host. If only certain domains are allowed, then this list enforces it. + If this option is explicitly set to `*`, then credentials can be created + for any domain. +
    • +
  • + key_option_specs + optional for Dynamic Key type, N/A for OTP type, + N/A for CA type + (String) + Comma separated option specification which will be prefixed to RSA + keys in the remote host's authorized_keys file. N.B.: Vault does + not check this string for validity. +
    • +
  • + ttl + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + The Time To Live value provided as a string duration with time suffix. + Hour is the largest suffix. If not set, uses the system default value + or the value of `max_ttl`, whichever is shorter. +
    • +
  • + max_ttl + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + The maximum Time To Live provided as a string duration with time + suffix. Hour is the largest suffix. If not set, defaults to the system + maximum lease TTL. +
    • +
  • + allowed_critical_options + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + A comma-separated list of critical options that certificates can have when + signed. To allow any critical options, set this to an empty string. Will + default to allowing any critical options. +
    • +
  • + allowed_extensions + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + A comma-separated list of extensions that certificates can have when + signed. To allow any critical options, set this to an empty string. Will + default to allowing any extensions. +
    • +
  • + default_critical_options + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + A map of critical options certificates should have if none are provided + when signing. This field takes in key value pairs in JSON format. Note + that these are not restricted by `allowed_critical_options`. Defaults + to none. +
    • +
  • + default_extensions + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + A map of extensions certificates should have if none are provided when + signing. This field takes in key value pairs in JSON format. Note that + these are not restricted by `allowed_extensions`. Defaults to none. +
    • +
  • + allow_user_certificates + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + If set, certificates are allowed to be signed for use as a 'user'. + Defaults to false. +
    • +
  • + allow_host_certificates + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + If set, certificates are allowed to be signed for use as a 'host'. + Defaults to false. +
    • +
  • + allow_bare_domains + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + If set, host certificates that are requested are allowed to use the base + domains listed in "allowed_users", e.g. "example.com". This + is a separate option as in some cases this can be considered a security + threat. Defaults to false. +
    • +
  • + allow_subdomains + N/A for Dynamic Key type, N/A for OTP type, + optional for CA type + If set, host certificates that are requested are allowed to use + subdomains of those listed in "allowed_users". Defaults + to false. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+ +#### GET + +
+
Description
+
+ Queries a named role. +
+ +
Method
+
GET
+ +
URL
+
`/ssh/roles/`
+ +
Parameters
+
None
+ +
Returns
+
Note: these are examples only. For a dynamic key role: + +```json +{ + "admin_user": "username", + "cidr_list": "x.x.x.x/y", + "default_user": "username", + "key": "", + "key_type": "dynamic", + "port": 22 +} +``` + +
+ +
For an OTP role: + +```json +{ + "cidr_list": "x.x.x.x/y", + "default_user": "username", + "key_type": "otp", + "port": 22 +} +``` +
+
For a CA role: + +```json +{ + "allow_bare_domains": false, + "allow_host_certificates": true, + "allow_subdomains": false, + "allow_user_certificates": true, + "allowed_critical_options": "", + "allowed_extensions": "", + "default_critical_options": {}, + "default_extensions": {}, + "max_ttl": "768h", + "ttl": "4h" +} +``` +
+ +#### LIST + +
+
Description
+
+ Returns a list of available roles. Only the role names are returned, not + any values. +
+ +
Method
+
LIST/GET
+ +
URL
+
`/ssh/roles` (LIST) or `/ssh/roles?list=true` (GET)
+ +
Parameters
+
+ None +
+ +
Returns
+
+ + ```json + { + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false + } + ``` + +
+
+ +#### DELETE + +
+
Description
+
+ Deletes a named role. +
+ +
Method
+
DELETE
+ +
URL
+
`/ssh/roles/`
+ +
Parameters
+
None
+ +
Returns
+
+ A `204` response code. +
+ +### /ssh/config/zeroaddress + +#### GET + +
+
Description
+
+ Returns the list of configured zero-address roles. +
+ +
Method
+
GET
+ +
URL
+
`/ssh/config/zeroaddress`
+ +
Parameters
+
None
+ +
Returns
+
+ +```json +{ + "lease_id":"", + "renewable":false, + "lease_duration":0, + "data":{ + "roles":[ + "otp_key_role" + ] + }, + "warnings":null, + "auth":null +} +``` + +
+ +#### POST + +
+
Description
+
+ Configures zero-address roles. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/config/zeroaddress`
+ +
Parameters
+
+
    +
  • + roles + required + A string containing comma separated list of role names which allows credentials to be requested + for any IP address. CIDR blocks previously registered under these roles will be ignored. +
    • +
+
+ +
Returns
+
+ A `204` response code. +
+ +#### DELETE + +
+
Description
+
+ Deletes the zero-address roles configuration. +
+ +
Method
+
DELETE
+ +
URL
+
`/ssh/config/zeroaddress`
+ +
Parameters
+
None
+ +
Returns
+
+ A `204` response code. +
+ + +### /ssh/creds/ +#### POST + +
+
Description
+
+ Creates credentials for a specific username and IP with the + parameters defined in the given role. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/creds/`
+ +
Parameters
+
+
    +
  • + username + optional + (String) + Username on the remote host. +
    • +
  • + ip + required + (String) + IP of the remote host. +
    • +
+
+ +
Returns
+
For a dynamic key role: + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "admin_user": "rajanadar", + "allowed_users": "", + "cidr_list": "x.x.x.x/y", + "default_user": "rajanadar", + "exclude_cidr_list": "x.x.x.x/y", + "install_script": "pretty_large_script", + "key": "5d9ee6a1-c787-47a9-9738-da243f4f69bf", + "key_bits": 1024, + "key_option_specs": "", + "key_type": "dynamic", + "port": 22 + }, + "warnings": null, + "auth": null +} +``` + +
+ +
For an OTP role: + +```json +{ + "lease_id": "sshs/creds/c3c2e60c-5a48-415a-9d5a-a41e0e6cdec5/3ee6ad28-383f-d482-2427-70498eba4d96", + "renewable": false, + "lease_duration": 2764800, + "data": { + "ip": "127.0.0.1", + "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2", + "key_type": "otp", + "port": 22, + "username": "rajanadar" + }, + "warnings": null, + "auth": null +} +``` +
+ + +### /ssh/lookup +#### POST + +
+
Description
+
+ Lists all of the roles with which the given IP is associated. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/lookup`
+ +
Parameters
+
+
    +
  • + ip + required + (String) + IP of the remote host. +
    • +
+
+ +
Returns
+
An array of roles as a secret structure. + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "roles": ["fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"] + }, + "warnings": null, + "auth": null +} +``` +
+ +### /ssh/verify +#### POST + +
+
Description
+
+ Verifies if the given OTP is valid. This is an unauthenticated + endpoint. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/verify`
+ +
Parameters
+
+
    +
  • + otp + required + (String) + One-Time-Key that needs to be validated. +
    • +
+
+ +
Returns
+
A `200` response code for a valid OTP. + +```json +{ + "lease_id":"", + "renewable":false, + "lease_duration":0, + "data":{ + "ip":"127.0.0.1", + "username":"rajanadar" + }, + "warnings":null, + "auth":null +} +``` + +
+ +
A `400` BadRequest response code with 'OTP not found' message, for an invalid OTP.
+ +### /ssh/config/ca +#### POST + +
+
Description
+
+ Allows submitting the CA information for the backend via an SSH key pair. + _If you have already set a certificate and key, they will be overridden._

+
+ +
Method
+
POST
+ +
URL
+
`/ssh/config/ca`
+ +
Parameters
+
+
    +
  • + private_key + optional + The private key part the SSH CA key pair; required if generate_signing_key is false. +
    • +
  • + public_key + optional + The public key part of the SSH CA key pair; required if generate_signing_key is false. +
    • +
  • + generate_signing_key + optional + Generate the signing key pair interally if true, otherwise use the private_key and public_key fields. + The generated public key will be returned so you can add it to your configuration. +
    • +
+
+ +
Returns
+
+ A `204` response code. And if generate_signing_key was true: +
+
+ ```json + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "public_key": "ssh-rsa AAAAHHNzaC1y...\n" + }, + "warnings": null + } + ``` +
+
+ +#### GET + +
+
Description
+
+ Reads the configured/generated public key. +
+ +
Method
+
GET
+ +
URL
+
`/ssh/config/ca`
+ +
Parameters
+
None
+ +
Returns
+
+ ```json + { + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "public_key": "ssh-rsa AAAAHHNzaC1y...\n" + }, + "warnings": null + } + ``` +
+
+ +### /ssh/sign +#### POST + +
+
Description
+
+ Signs an SSH public key based on the supplied parameters, subject to the + restrictions contained in the role named in the endpoint. +
+ +
Method
+
POST
+ +
URL
+
`/ssh/sign/`
+ +
Parameters
+
+
    +
  • + public_key + required + SSH public key that should be signed. +
    • +
  • + ttl + optional + Requested Time To Live. Cannot be greater than the role's `max_ttl` + value. If not provided, the role's `ttl` value will be used. Note that + the role values default to system values if not explicitly set. +
    • +
  • + valid_principals + optional + Valid principals, either usernames or hostnames, that the certificate + should be signed for. Defaults to none. +
    • +
  • + cert_type + optional + Type of certificate to be created; either "user" or "host". Defaults to + "user". +
    • +
  • + key_id + optional + Key id that the created certificate should have. If not specified, + the display name of the token will be used. +
    • +
  • + critical_options + optional + A map of the critical options that the certificate should be signed for. + Defaults to none. +
    • +
  • + extensions + optional + A map of the extensions that the certificate should be signed for. + Defaults to none +
    • +
+
+ +
Returns
+
+ + ```json + { + "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993", + "renewable": false, + "lease_duration": 21600, + "data": { + "serial_number": "f65ed2fd21443d5c", + "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n" + }, + "auth": null + } + ``` + +
+
+======= +The SSH secret backend has a full HTTP API. Please see the +[SSH secret backend API](/docs/http/secret/ssh/index.html) for more +details. +>>>>>>> e54ffcd1... Break out API documentation for secret backends diff --git a/website/source/docs/http/secret/transit/index.html.md b/website/source/docs/http/secret/transit/index.html.md new file mode 100644 index 000000000..00b3a65c8 --- /dev/null +++ b/website/source/docs/http/secret/transit/index.html.md @@ -0,0 +1,859 @@ +--- +layout: "http" +page_title: "Transit Secret Backend - HTTP API" +sidebar_current: "docs-http-secret-transit" +description: |- + TODO +--- + +# Transit Secret Backend HTTP API + +This is the API documentation for the Vault Transit secret backend. For general +information about the usage and operation of the Transit backend, please see the +[Vault Transit backend documentation](/docs/secrets/transit/index.html). + +This documentation assumes the Transit backend is mounted at the `/transit` +path in Vault. Since it is possible to mount secret backends at any location, +please update your API calls accordingly. + +## Create Key + +This endpoint creates a new named encryption key of the specified type. The +values set here cannot be changed after key creation. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/keys/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + create. This is specified as part of the URL. + +- `convergent_encryption` `(bool: false)` – If enabled, the key will support + convergent encryption, where the same plaintext creates the same ciphertext. + This requires _derived_ to be set to `true`. When enabled, each + encryption(/decryption/rewrap/datakey) operation will derive a `nonce` value + rather than randomly generate it. Note that while this is useful for + particular situations, all nonce values used with a given context value **must + be unique** or it will compromise the security of your key, and the key space + for nonces is 96 bit -- not as large as the AES key itself. + +- `derived` `(bool: false)` – Specifies if key derivation kist be used. If + enabled, all encrypt/decrypt requests to this named key must provide a context + which is used for key derivation. + +- `exportable` `(bool: false)` – Specifies if the raw key is exportable. + +- `type` `(string: "aes256-gcm96")` – Specifies the type of key to create. The + currently-supported types are: + + - `aes256-gcm96` – AES-256 wrapped with GCM using a 12-byte nonce size (symmetric) + - `ecdsa-p256` – ECDSA using the P-256 elliptic curve (asymmetric) + +### Sample Payload + +```json +{ + "type": "ecdsa-p256", + "derived": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/keys/my-key +``` + +## Read Key + +This endpoint returns information about a named encryption key. The `keys` +object shows the creation time of each key version; the values are not the keys +themselves. Depending on the type of key, different information may be returned, +e.g. an asymmetric key will return its public key in a standard format for the +type. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/transit/keys/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + read. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/transit/keys/my-key +``` + +### Sample Response + +```json +{ + "data": { + "type": "aes256-gcm96", + "deletion_allowed": false, + "derived": false, + "exportable": false, + "keys": { + "1": 1442851412 + }, + "min_decryption_version": 0, + "name": "foo", + "supports_encryption": true, + "supports_decryption": true, + "supports_derivation": true, + "supports_signing": false + } +} +``` + +## List Keys + +This endpoint returns a list of keys. Only the key names are returned (not the +actual keys themselves). + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/transit/keys` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/transit/keys +``` + +### Sample Response + +```json +{ + "data": { + "keys": ["foo", "bar"] + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false +} +``` + +## Delete Key + +This endpoint deletes a named encryption key. It will no longer be possible to +decrypt any data encrypted with the named key. Because this is a potentially +catastrophic operation, the `deletion_allowed` tunable must be set in the key's +`/config` endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/transit/keys/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + delete. This is specified as part of the URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/transit/keys/my-key +``` + +#### Update Key Configuration + +This endpoint allows tuning configuration values for a given key. (These values +are returned during a read operation on the named key.) + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/keys/:name/config` | `204 (empty body)` | + +### Parameters + +- `min_decryption_version` `(int: 0)` – Specifies the minimum version of + ciphertext allowed to be decrypted. Adjusting this as part of a key rotation + policy can prevent old copies of ciphertext from being decrypted, should they + fall into the wrong hands. For signatures, this value controls the minimum + version of signature that can be verified against. For HMACs, this controls + the minimum version of a key allowed to be used as the key for the HMAC + function. + +- `deletion_allowed` `(bool: false)`- Specifies if the key is allowed to be + deleted. + +### Sample Payload + +```json +{ + "deletion_allowed": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/keys/my-key/config +``` + +## Rotate Key + +This endpoint rotates the version of the named key. After rotation, new +plaintext requests will be encrypted with the new version of the key. To upgrade +ciphertext to be encrypted with the latest version of the key, use the `rewrap` +endpoint. This is only supported with keys that support encryption and +decryption operations. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/keys/:name/rotate` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/transit/keys/my-key/rotate +``` + +## Read Key + +This endpoint returns the named key. The `keys` object shows the value of the +key for each version. If `version` is specified, the specific version will be +returned. If `latest` is provided as the version, the current key will be +provided. Depending on the type of key, different information may be returned. +The key must be exportable to support this operation and the version must still +be valid. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/transit/export/:key_type/:name(/:version)` | `200 application/json` | + +### Parameters + +- `key_type` `(string: )` – Specifies the type of the key to export. + This is specified as part of the URL. Valid values are: + + - `encryption-key` + - `signing-key` + - `hmac-key` + +- `name` `(string: )` – Specifies the name of the key to read + information about. This is specified as part of the URL. + +- `version` `(int: "")` – Specifies the version of the key to read. If omitted, + all versions of the key will be returned. This is specified as part of the + URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/transit/export/encryption-key/my-key/1 +``` + +### Sample Response + +```json +{ + "data": { + "name": "foo", + "keys": { + "1": "eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=", + "2": "Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE=" + } + } +} +``` + +## Encrypt Data + +This endpoint encrypts the provided plaintext using the named key. Currently, +this only supports symmetric keys. This path supports the `create` and `update` +policy capabilities as follows: if the user has the `create` capability for this +endpoint in their policies, and the key does not exist, it will be upserted with +default values (whether the key requires derivation depends on whether the +context parameter is empty or not). If the user only has `update` capability and +the key does not exist, an error will be returned. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/encrypt/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + encrypt against. This is specified as part of the URL. + +- `plaintext` `(string: )` – Specifies **base64 encoded** plaintext to + be encoded. + +- `context` `(string: "")` – Specifies the **base64 encoded** context for key + derivation. This is required if key derivation is enabled for this key. + +- `nonce` `(string: "")` – Specifies the **base64 encoded** nonce value. This + must be provided if convergent encryption is enabled for this key and the key + was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The + value must be exactly 96 bits (12 bytes) long and the user must ensure that + for any given context (and thus, any given encryption key) this nonce value is + **never reused**. + +- `batch_input` `(array: nil)` – Specifies a list of items to be + encrypted in a single batch. When this parameter is set, if the parameters + 'plaintext', 'context' and 'nonce' are also set, they will be ignored. The + format for the input is: + + ```json + [ + { + "context": "c2FtcGxlY29udGV4dA==", + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" + }, + { + "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" + }, + ] + ``` + +- `type` `(string: "aes256-gcm96")` –This parameter is required when encryption + key is expected to be created. When performing an upsert operation, the type + of key to create. Currently, "aes256-gcm96" (symmetric) is the only type + supported. + +- `convergent_encryption` `(string: "")` – This parameter will only be used when + a key is expected to be created. Whether to support convergent encryption. + This is only supported when using a key with key derivation enabled and will + require all requests to carry both a context and 96-bit (12-byte) nonce. The + given nonce will be used in place of a randomly generated nonce. As a result, + when the same context and nonce are supplied, the same ciphertext is + generated. It is _very important_ when using this mode that you ensure that + all nonces are unique for a given context. Failing to do so will severely + impact the ciphertext's security. + +### Sample Payload + +```json +{ + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/encrypt/my-key +``` + +### Sample Response + +```json +{ + "data": { + "ciphertext": "vault:v1:abcdefgh" + } +} +``` + +## Decrypt Data + +This endpoint decrypts the provided ciphertext using the named key. Currently, +this only supports symmetric keys. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/decrypt/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + decrypt against. This is specified as part of the URL. + +- `ciphertext` `(string: )` – Specifies the ciphertext to decrypt. + +- `context` `(string: "")` – Specifies the **base64 encoded** context for key + derivation. This is required if key derivation is enabled. + +- `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during + encryption. Must be provided if convergent encryption is enabled for this key + and the key was generated with Vault 0.6.1. Not required for keys created in + 0.6.2+. + +- `batch_input` `(array: nil)` – Specifies a list of items to be + decrypted in a single batch. When this parameter is set, if the parameters + 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. Format + for the input goes like this: + + ```json + [ + { + "context": "c2FtcGxlY29udGV4dA==", + "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" + }, + { + "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" + }, + ] + ``` + +### Sample Payload + +```json +{ + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/decrypt/my-key +``` + +### Sample Response + +```json +{ + "data": { + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Rewrap Data + +This endpoint rewrapw the provided ciphertext using the latest version of the +named key. Because this never returns plaintext, it is possible to delegate this +functionality to untrusted users or scripts. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/rewrap/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + re-encrypt against. This is specified as part of the URL. + +- `ciphertext` `(string: )` – Specifies the ciphertext to re-encrypt. + +- `context` `(string: "")` – Specifies the **base64 encoded** context for key + derivation. This is required if key derivation is enabled. + +- `nonce` `(string: "")` – Specifies a base64 encoded nonce value used during + encryption. Must be provided if convergent encryption is enabled for this key + and the key was generated with Vault 0.6.1. Not required for keys created in + 0.6.2+. + +- `batch_input` `(array: nil)` – Specifies a list of items to be + decrypted in a single batch. When this parameter is set, if the parameters + 'ciphertext', 'context' and 'nonce' are also set, they will be ignored. Format + for the input goes like this: + + ```json + [ + { + "context": "c2FtcGxlY29udGV4dA==", + "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" + }, + { + "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" + }, + ] + ``` + +### Sample Payload + +```json +{ + "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/rewrap/my-key +``` + +### Sample Response + +```json +{ + "data": { + "ciphertext": "vault:v2:abcdefgh" + } +} +``` + +## Generate Data Key + +This endpoint generates a new high-entropy key and the value encrypted with the +named key. Optionally return the plaintext of the key as well. Whether plaintext +is returned depends on the path; as a result, you can use Vault ACL policies to +control whether a user is allowed to retrieve the plaintext value of a key. This +is useful if you want an untrusted user or operation to generate keys that are +then made available to trusted users. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/datakey/:type/:name` | `200 application/json` | + +### Parameters + +- `type` `(string: )` – Specifies the type of key to generate. If + `plaintext`, the plaintext key will be returned along with the ciphertext. If + `wrapped`, only the ciphertext value will be returned. This is specified as + part of the URL. + +- `name` `(string: )` – Specifies the name of the encryption key to + re-encrypt against. This is specified as part of the URL. + +- `context` `(string: "")` – Specifies the key derivation context, provided as a + base64-encoded string. This must be provided if derivation is enabled. + +- `nonce` `(string: "")` – Specifies a nonce value, provided as base64 encoded. + Must be provided if convergent encryption is enabled for this key and the key + was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The + value must be exactly 96 bits (12 bytes) long and the user must ensure that + for any given context (and thus, any given encryption key) this nonce value is + **never reused**. + +- `bits` `(int: 256)` – Specifies the number of bits in the desired key. Can be + 128, 256, or 512. + +### Sample Payload + +```json +{ + "context": "Ab3==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/datakey/plaintext/my-key +``` + +### Sample Response + +```json +{ + "data": { + "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", + "ciphertext": "vault:v1:abcdefgh" + } +} +``` + +## Generate Random Bytes + +This endpoint returns high-quality random bytes of the specified length. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/random(/:bytes)` | `200 application/json` | + +### Parameters + +- `bytes` `(int: 32)` – Specifies the number of bytes to return. This value can + be specified either in the request body, or as a part of the URL. + +- `format` `(string: "base64")` – Specifies the output encoding. Valid options + are `hex` or `base64`. + +### Sample Payload + +```json +{ + "format": "hex" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/random/164 +``` + +### Sample Response + +```json +{ + "data": { + "random_bytes": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Hash Data + +This endpoint returns the cryptographic hash of given data using the specified +algorithm. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/hash(/:algorithm)` | `200 application/json` | + +### Parameters + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +### Sample Payload + +```json +{ + "input": "adba32==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/hash/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "sum": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Generate HMAC with Key + +This endpoint returns the digest of given data using the specified hash +algorithm and the named key. The key can be of any type supported by `transit`; +the raw key will be marshaled into bytes to be used for the HMAC function. If +the key is of a type that supports rotation, the latest (current) version will +be used. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/hmac/:name(/:algorithm)` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + generate hmac against. This is specified as part of the URL. + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +### Sample Payload + +```json +{ + "input": "adba32==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/hmac/my-key/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "hmac": "dGhlIHF1aWNrIGJyb3duIGZveAo=" + } +} +``` + +## Sign Data with Key + +This endpoint returns the cryptographic signature of the given data using the +named key and the specified hash algorithm. The key must be of a type that +supports signing. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/sign/:name(/:algorithm)` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + generate hmac against. This is specified as part of the URL. + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +### Sample Payload + +```json +{ + "input": "adba32==" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/sign/my-key/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "signature": "vault:v1:MEUCIQCyb869d7KWuA0hBM9b5NJrmWzMW3/pT+0XYCM9VmGR+QIgWWF6ufi4OS2xo1eS2V5IeJQfsi59qeMWtgX0LipxEHI=" + } +} +``` + +## Verify Data with Key + +This endpoint returns whether the provided signature is valid for the given +data. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/transit/verify/:name(/:algorithm)` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the encryption key to + generate hmac against. This is specified as part of the URL. + +- `algorithm` `(string: "sha2-256")` – Specifies the hash algorithm to use. This + can also be specified as part of the URL. Currently-supported algorithms are: + + - `sha2-224` + - `sha2-256` + - `sha2-384` + - `sha2-512` + +- `input` `(string: )` – Specifies the **base64 encoded** input data. + +- `format` `(string: "hex")` – Specifies the output encoding. This can be either + `hex` or `base64`. + +- `signature` `(string: "")` – Specifies the signature output from the + `/transit/sign` function. Either this must be supplied or `hmac` must be + supplied. + +- `hmac` `(string: "")` – Specifies the signature output from the + `/transit/hmac` function. Either this must be supplied or `signature` must be + supplied. + +### Sample Payload + +```json +{ + "input": "abcd13==", + "signature": "vault:v1:MEUCIQCyb869d7KWuA..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/transit/verify/my-key/sha2-512 +``` + +### Sample Response + +```json +{ + "data": { + "valid": true + } +} +``` diff --git a/website/source/docs/secrets/aws/index.html.md b/website/source/docs/secrets/aws/index.html.md index c352d3da9..d3bc154fd 100644 --- a/website/source/docs/secrets/aws/index.html.md +++ b/website/source/docs/secrets/aws/index.html.md @@ -45,7 +45,7 @@ The following parameters are required: credentials. - `region` the AWS region for API calls. -Note: the client uses the official AWS SDK and will use environment variable or IAM +Note: the client uses the official AWS SDK and will use environment variable or IAM role-provided credentials if available. The next step is to configure a role. A role is a logical name that maps @@ -159,7 +159,7 @@ Here is an example IAM policy that would grant these permissions: ``` Note that this policy example is unrelated to the policy you wrote to `aws/roles/deploy`. -This policy example should be applied to the IAM user (or role) associated with +This policy example should be applied to the IAM user (or role) associated with the root credentials that you wrote to `aws/config/root`. You have to apply it yourself in IAM. The policy you wrote to `aws/roles/deploy` is the policy you want the AWS secret backend to apply to the temporary credentials it returns @@ -364,341 +364,6 @@ errors for exceeding the AWS limit of 32 characters on STS token names. ## API -### /aws/config/root -#### POST - -
-
Description
-
- Configures the root IAM credentials used. - If static credentials are not provided using - this endpoint, then the credentials will be retrieved from the - environment variables `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` and `AWS_REGION` - respectively. If the credentials are still not found and if the - backend is configured on an EC2 instance with metadata querying - capabilities, the credentials are fetched automatically. -
- -
Method
-
POST
- -
URL
-
`/aws/config/root`
- -
Parameters
-
-
    -
  • - access_key - required - The AWS Access Key -
    • -
  • - secret_key - required - The AWS Secret Key -
    • -
  • - region - required - The AWS region for API calls -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /aws/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. -
- -
Method
-
POST
- -
URL
-
`/aws/config/lease`
- -
Parameters
-
-
    -
  • - lease - required - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - lease_max - required - The maximum lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /aws/roles/ -#### POST - -
-
Description
-
- Creates or updates a named role. -
- -
Method
-
POST
- -
URL
-
`/aws/roles/`
- -
Parameters
-
-
    -
  • - policy - required (unless arn specified) - The IAM policy in JSON format. -
    • -
  • - arn - required (unless policy specified) - The full ARN reference to the desired existing policy -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries a named role. -
- -
Method
-
GET
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript - { - "data": { - "policy": "..." - } - } - ``` - ```javascript - { - "data": { - "arn": "..." - } - } - ``` -
-
- -#### DELETE - -
-
Description
-
- Deletes a named role. -
- -
Method
-
DELETE
- -
URL
-
`/aws/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -#### LIST - -
-
Description
-
- Returns a list of existing roles in the backend -
- -
Method
-
LIST/GET
- -
URL
-
`/aws/roles` (LIST) or `/aws/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript -{ - "auth": null, - "warnings": null, - "wrap_info": null, - "data": { - "keys": [ - "devrole", - "prodrole", - "testrole" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} - ``` -
-
- - -### /aws/creds/ -#### GET - -
-
Description
-
- Generates a dynamic IAM credential based on the named role. -
- -
Method
-
GET
- -
URL
-
`/aws/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript - { - "data": { - "access_key": "...", - "secret_key": "...", - "security_token": null - } - } - ``` -
-
- - -### /aws/sts/ -#### GET - -
-
Description
-
- Generates a dynamic IAM credential with an STS token based on the named - role. The TTL will be 3600 seconds (one hour). -
- -
Method
-
GET
- -
URL
-
`/aws/sts/`
- -
Parameters
-
- None -
- -
Returns
-
- ```javascript - { - "data": { - "access_key": "...", - "secret_key": "...", - "security_token": "..." - } - } - ``` -
-
- -#### POST - -
-
Description
-
- Generates a dynamic IAM credential with an STS token based on the named - role and the given TTL (defaults to 3600 seconds, or one hour). -
- -
Method
-
POST
- -
URL
-
`/aws/sts/`
- -
Parameters
-
-
    -
  • - ttl - optional - The TTL to use for the STS token. -
    • -
-
- -
Returns
-
- ```javascript - { - "data": { - "access_key": "...", - "secret_key": "...", - "security_token": "..." - } - } - ``` -
-
+The AWS secret backend has a full HTTP API. Please see the +[AWS secret backend API](/docs/http/secret/aws/index.html) for more +details. diff --git a/website/source/docs/secrets/cassandra/index.html.md b/website/source/docs/secrets/cassandra/index.html.md index 08fd6ce7a..0ac9dcbc6 100644 --- a/website/source/docs/secrets/cassandra/index.html.md +++ b/website/source/docs/secrets/cassandra/index.html.md @@ -94,262 +94,6 @@ subpath for interactive help output. ## API -### /cassandra/config/connection -#### POST - -
-
Description
-
- Configures the connection information used to communicate with Cassandra. - TLS works as follows:

-
    -
  • - • If `tls` is set to true, the connection will use TLS; this happens - automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set -
    • -
  • - • If `insecure_tls` is set to true, the connection will not perform - verification of the server certificate; this also sets `tls` to true -
    • -
  • - • If only `issuing_ca` is set in `pem_json`, or the only certificate in - `pem_bundle` is a CA certificate, the given CA certificate will be used - for server certificate verification; otherwise the system CA - certificates will be used -
    • -
  • - • If `certificate` and `private_key` are set in `pem_bundle` or - `pem_json`, client auth will be turned on for the connection -
    • -
- `pem_bundle` should be a PEM-concatenated bundle of a private key + client - certificate, an issuing CA certificate, or both. `pem_json` should contain - the same information; for convenience, the JSON format is the same as that - output by the issue command from the PKI backend. -
- -
Method
-
POST
- -
URL
-
`/cassandra/config/connection`
- -
Parameters
-
-
    -
  • - hosts - required - A set of comma-deliniated Cassandra hosts to connect to. -
    • -
  • - username - required - The username to use for superuser access. -
    • -
  • - password - required - The password corresponding to the given username. -
    • -
  • - tls - optional - Whether to use TLS when connecting to Cassandra. -
    • -
  • - insecure_tls - optional - Whether to skip verification of the server certificate when using TLS. -
    • -
  • - pem_bundle - optional - Concatenated PEM blocks containing a certificate and private key; - a certificate, private key, and issuing CA certificate; or just a CA - certificate. -
    • -
  • - pem_json - optional - JSON containing a certificate and private key; - a certificate, private key, and issuing CA certificate; or just a CA - certificate. For convenience format is the same as the output of the - `issue` command from the `pki` backend; see [the pki documentation](https://www.vaultproject.io/docs/secrets/pki/index.html). -
    • -
  • - protocol_version - optional - The CQL protocol version to use. Defaults to 2. -
    • -
  • - connect_timeout - optional - The connection timeout to use. Defaults to 5 seconds. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /cassandra/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/cassandra/roles/`
- -
Parameters
-
-
    -
  • - creation_cql - optional - The CQL statements executed to create and configure the new user. Must - be a semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{username}}' and '{{password}}' values will be - substituted; it is required that these parameters are in single quotes. - The default creates a non-superuser user with no authorization grants. -
    • -
  • - rollback_cql - optional - The CQL statements executed to attempt a rollback if an error is - encountered during user creation. The default is to delete the user. - Must be a semicolon-separated string, a base64-encoded - semicolon-separated string, a serialized JSON string array, or a - base64-encoded serialized JSON string array. The '{{username}}' and - '{{password}}' values will be substituted; it is required that these - parameters are in single quotes. -
    • -
  • - lease - optional - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - consistency - optional - The consistency level value provided as a string. Determines the - consistency level used for operations performed on the Cassandra - database. Defaults to a consistency level of Quorum. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/cassandra/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "creation_cql": "CREATE USER...", - "rollback_cql": "DROP USER...", - "lease": "12h", - "consistency": "Quorum" - } - } - ``` - -
-
- - -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/cassandra/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /cassandra/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/cassandra/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "vault-root-1430158508-126", - "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" - } - } - ``` - -
-
+The Cassandra secret backend has a full HTTP API. Please see the +[Cassandra secret backend API](/docs/http/secret/cassandra/index.html) for more +details. diff --git a/website/source/docs/secrets/consul/index.html.md b/website/source/docs/secrets/consul/index.html.md index b1fd2c4fa..052f2cfb7 100644 --- a/website/source/docs/secrets/consul/index.html.md +++ b/website/source/docs/secrets/consul/index.html.md @@ -98,184 +98,6 @@ Permission denied ## API -### /consul/config/access -#### POST - -
-
Description
-
- Configures the access information for Consul. -
- -
Method
-
POST
- -
URL
-
`/consul/config/access`
- -
Parameters
-
-
    -
  • - address - required - The address of the Consul instance, provided as host:port -
    • -
  • - scheme - optional - The URL scheme to use. Defaults to HTTP, as Consul does not expose HTTPS by default. -
    • -
  • - token - required - The Consul ACL token to use. Must be a management type token. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /consul/roles/ -#### POST - -
-
Description
-
- Creates or updates the Consul role definition. -
- -
Method
-
POST
- -
URL
-
`/consul/roles/`
- -
Parameters
-
-
    -
  • - policy - required - The base64 encoded Consul ACL policy. This is documented in [more - detail here](https://www.consul.io/docs/internals/acl.html). Required - unless the `token_type` is `management`. -
    • -
  • - token_type - optional - The type of token to create using this role: `client` or `management`. - If `management`, the `policy` parameter is not required. -
    • -
  • - lease - optional - The lease value provided as a string duration with time suffix. Hour is - the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries a Consul role definition. -
- -
Method
-
GET
- -
URL
-
`/consul/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "policy": "abcdef=", - "lease": "1h0m0s", - "token_type": "client" - } - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a Consul role definition. -
- -
Method
-
DELETE
- -
URL
-
`/consul/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /consul/creds/ -#### GET - -
-
Description
-
- Generates a dynamic Consul token based on the role definition. -
- -
Method
-
GET
- -
URL
-
`/consul/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "token": "973a31ea-1ec4-c2de-0f63-623f477c2510" - } - } - ``` - -
-
+The Consul secret backend has a full HTTP API. Please see the +[Consul secret backend API](/docs/http/secret/consul/index.html) for more +details. diff --git a/website/source/docs/secrets/cubbyhole/index.html.md b/website/source/docs/secrets/cubbyhole/index.html.md index 860493ac2..79d91f8b6 100644 --- a/website/source/docs/secrets/cubbyhole/index.html.md +++ b/website/source/docs/secrets/cubbyhole/index.html.md @@ -89,139 +89,6 @@ As expected, the value previously set is returned to us. ## API -#### GET - -
-
Description
-
- Retrieves the secret at the specified location. -
- -
Method
-
GET
- -
URL
-
`/cubbyhole/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "foo": "bar" - }, - "lease_duration": 0, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of secret entries at the specified location. Folders are - suffixed with `/`. The input must be a folder; list on a file will not - return a value. The values themselves are not accessible via this command. -
- -
Method
-
LIST/GET
- -
URL
-
`/cubbyhole/` (LIST) or `/cubbyhole/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- The example below shows output for a query path of `cubbyhole/` when there - are secrets at `cubbyhole/foo` and `cubbyhole/foo/bar`; note the difference - in the two entries. - - ```javascript - { - "auth": null, - "data": { - "keys": ["foo", "foo/"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### POST/PUT - -
-
Description
-
- Stores a secret at the specified location. -
- -
Method
-
POST/PUT
- -
URL
-
`/cubbyhole/`
- -
Parameters
-
-
    -
  • - (key) - optional - A key, paired with an associated value, to be held at the - given location. Multiple key/value pairs can be specified, - and all will be returned on a read operation. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### DELETE - -
-
Description
-
- Deletes the secret at the specified location. -
- -
Method
-
DELETE
- -
URL
-
`/cubbyhole/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
+The Cubbyhole secret backend has a full HTTP API. Please see the +[Cubbyhole secret backend API](/docs/http/secret/cubbyhole/index.html) for more +details. diff --git a/website/source/docs/secrets/generic/index.html.md b/website/source/docs/secrets/generic/index.html.md index 937b9ff31..7c67a8047 100644 --- a/website/source/docs/secrets/generic/index.html.md +++ b/website/source/docs/secrets/generic/index.html.md @@ -70,145 +70,6 @@ seconds (one hour) as specified. ## API -#### GET - -
-
Description
-
- Retrieves the secret at the specified location. -
- -
Method
-
GET
- -
URL
-
`/secret/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "foo": "bar" - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of key names at the specified location. Folders are - suffixed with `/`. The input must be a folder; list on a file will not - return a value. Note that no policy-based filtering is performed on keys; - do not encode sensitive information in key names. The values themselves - are not accessible via this command. -
- -
Method
-
LIST/GET
- -
URL
-
`/secret/` (LIST) or `/secret/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- The example below shows output for a query path of `secret/` when there are - secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two - entries. - - ```javascript - { - "auth": null, - "data": { - "keys": ["foo", "foo/"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### POST/PUT - -
-
Description
-
- Stores a secret at the specified location. If the value does not yet exist, - the calling token must have an ACL policy granting the `create` capability. - If the value already exists, the calling token must have an ACL policy - granting the `update` capability. -
- -
Method
-
POST/PUT
- -
URL
-
`/secret/`
- -
Parameters
-
-
    -
  • - (key) - optional - A key, paired with an associated value, to be held at the given - location. Multiple key/value pairs can be specified, and all will be - returned on a read operation. A key called `ttl` will trigger some - special behavior; see above for details. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### DELETE - -
-
Description
-
- Deletes the secret at the specified location. -
- -
Method
-
DELETE
- -
URL
-
`/secret/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
+The Generic secret backend has a full HTTP API. Please see the +[Generic secret backend API](/docs/http/secret/generic/index.html) for more +details. diff --git a/website/source/docs/secrets/mongodb/index.html.md b/website/source/docs/secrets/mongodb/index.html.md index 0406ea3b8..bd8dccca5 100644 --- a/website/source/docs/secrets/mongodb/index.html.md +++ b/website/source/docs/secrets/mongodb/index.html.md @@ -120,368 +120,6 @@ applications are restricted in the credentials they are allowed to read. ## API -### /mongodb/config/connection -#### POST - -
-
Description
-
- Configures the standard connection string (URI) used to communicate with MongoDB. -
- -
Method
-
POST
- -
URL
-
`/mongodb/config/connection`
- -
Parameters
-
-
    -
  • - uri - required - The MongoDB standard connection string (URI) -
    • -
-
- -
-
    -
  • - verify_connection - optional - If set, uri is verified by actually connecting to the database. - Defaults to true. -
    • -
-
- -
Returns
-
- A `200` response code. -
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": null, - "wrap_info": null, - "warnings": [ - "Read access to this endpoint should be controlled via ACLs as it will return the connection URI as it is, including passwords, if any." - ], - "auth": null - } - ``` - -
-
- -#### GET - -
-
Description
-
- Queries the connection configuration. Access to this endpoint should be controlled via ACLs as it will return the - connection URI as it is, including passwords, if any. -
- -
Method
-
GET
- -
URL
-
`/mongodb/config/connection`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "uri": "mongodb://admin:Password!@mongodb.acme.com:27017/admin?ssl=true" - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /mongodb/config/lease -#### POST - -
-
Description
-
- Configures the default lease TTL settings for credentials generated by the mongodb backend. -
- -
Method
-
POST
- -
URL
-
`/mongodb/config/lease`
- -
Parameters
-
-
    -
  • - ttl - optional - The ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - max_ttl - optional - The maximum ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the lease configuration. -
- -
Method
-
GET
- -
URL
-
`/mongodb/config/lease`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "max_ttl": 60, - "ttl": 60 - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /mongodb/roles/\ -#### POST - -
-
Description
-
- Creates or updates a role definition. -
- -
Method
-
POST
- -
URL
-
`/mongodb/roles/`
- -
Parameters
-
-
    -
  • - db - required - The name of the database users should be created in for this role. -
    • -
  • - roles - optional - MongoDB roles to assign to the users generated for this role. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/mongodb/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "db": "foo", - "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]" - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/mongodb/roles` (LIST) or `/mongodb/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "keys": [ - "dev", - "prod" - ] - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/mongodb/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /mongodb/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/mongodb/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "mongodb/creds/readonly/e64e79d8-9f56-e379-a7c5-373f9b4ee3d8", - "renewable": true, - "lease_duration": 3600, - "data": { - "db": "foo", - "password": "de0f7b50-d700-54e5-4e81-5c3724283999", - "username": "vault-token-b32098cb-7ff2-dcf5-83cd-d5887cedf81b" - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` - -
-
+The MongoDB secret backend has a full HTTP API. Please see the +[MongoDB secret backend API](/docs/http/secret/mongodb/index.html) for more +details. diff --git a/website/source/docs/secrets/mssql/index.html.md b/website/source/docs/secrets/mssql/index.html.md index b10d7c783..79f40dfc4 100644 --- a/website/source/docs/secrets/mssql/index.html.md +++ b/website/source/docs/secrets/mssql/index.html.md @@ -110,301 +110,6 @@ allowed to read. ## API -### /mssql/config/connection -#### POST - -
-
Description
-
- Configures the connection DSN used to communicate with Sql Server. -
- -
Method
-
POST
- -
URL
-
`/mssql/config/connection`
- -
Parameters
-
-
    -
  • - connection_string - required - The MSSQL DSN -
    • -
-
-
-
    -
  • - max_open_connections - optional - Maximum number of open connections to the database. - Defaults to 2. -
    • -
-
-
-
    -
  • - verify_connection - optional - If set, connection_string is verified by actually connecting to the database. - Defaults to true. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /mssql/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. -
- -
Method
-
POST
- -
URL
-
`/mssql/config/lease`
- -
Parameters
-
-
    -
  • - ttl - required - The ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - max_ttl - required - The maximum ttl value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the lease configuration. -
- -
Method
-
GET
- -
URL
-
`/mssql/config/lease`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "max_ttl": "5h", - "ttl": "1h", - "ttl_max": "5h" - }, - "wrap_info": null, - "warnings": ["The field ttl_max is deprecated and will be removed in a future release. Use max_ttl instead."], - "auth": null - } - ``` - -
-
- -### /mssql/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/mssql/roles/`
- -
Parameters
-
-
    -
  • - sql - required - The SQL statements executed to create and configure the role. The - '{{name}}' and '{{password}}' values will be substituted. Must be a - semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/mssql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "sql": "CREATE LOGIN..." - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/mssql/roles` (LIST) or `/mssql/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/mssql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /mssql/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/mssql/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "root-a147d529-e7d6-4a16-8930-4c3e72170b19", - "password": "ee202d0d-e4fd-4410-8d14-2a78c5c8cb76" - } - } - ``` - -
-
+The MSSQL secret backend has a full HTTP API. Please see the +[MSSQL secret backend API](/docs/http/secret/mssql/index.html) for more +details. diff --git a/website/source/docs/secrets/mysql/index.html.md b/website/source/docs/secrets/mysql/index.html.md index 0986dbb99..c169af73b 100644 --- a/website/source/docs/secrets/mysql/index.html.md +++ b/website/source/docs/secrets/mysql/index.html.md @@ -109,7 +109,7 @@ allowed to read. Optionally, you may configure both the number of characters from the role name that are truncated to form the display name portion of the mysql username -interpolated into the `{{name}}` field: the default is 10. +interpolated into the `{{name}}` field: the default is 10. You may also configure the total number of characters allowed in the entire generated username (the sum of the display name and uuid portions); the @@ -119,309 +119,6 @@ the default on versions prior to that. ## API -### /mysql/config/connection -#### POST - -
-
Description
-
- Configures the connection DSN used to communicate with MySQL. -
- -
Method
-
POST
- -
URL
-
`/mysql/config/connection`
- -
Parameters
-
-
    -
  • - connection_url - required - The MySQL DSN -
    • -
-
-
-
    -
  • - value - optional -
    • -
-
-
-
    -
  • - max_open_connections - optional - Maximum number of open connections to the database. - Defaults to 2. -
    • -
-
-
-
    -
  • - max_idle_connections - optional - Maximum number of idle connections to the database. A zero uses the value of `max_open_connections` and a negative value disables idle connections. If larger than `max_open_connections` it will be reduced to be equal. -
    • -
-
-
-
    -
  • - verify_connection - optional - If set, connection_url is verified by actually connecting to the database. - Defaults to true. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /mysql/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. - If not configured, leases default to 1 hour. This is a root - protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/mysql/config/lease`
- -
Parameters
-
-
    -
  • - lease - required - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - lease_max - required - The maximum lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /mysql/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/mysql/roles/`
- -
Parameters
-
-
    -
  • - sql - required - The SQL statements executed to create and configure a user. Must be a - semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{name}}' and '{{password}}' values will be - substituted. -
    • -
  • - revocation_sql - optional - The SQL statements executed to revoke a user. Must be a - semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{name}}' value will be substituted. -
    • -
  • - rolename_length - optional - Determines how many characters from the role name will be used - to form the mysql username interpolated into the '{{name}}' field - of the sql parameter. The default is 4. -
    • -
  • - displayname_length - optional - Determines how many characters from the token display name will be used - to form the mysql username interpolated into the '{{name}}' field - of the sql parameter. The default is 4. -
    • -
  • - username_length - optional - Determines the maximum total length in characters of the - mysql username interpolated into the '{{name}}' field - of the sql parameter. The default is 16. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/mysql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "sql": "CREATE USER..." - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/mysql/roles` (LIST) or `/mysql/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/mysql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /mysql/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/mysql/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "user-role-aefa63", - "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" - } - } - ``` - -
-
- +The MySQL secret backend has a full HTTP API. Please see the +[MySQL secret backend API](/docs/http/secret/mysql/index.html) for more +details. diff --git a/website/source/docs/secrets/pki/index.html.md b/website/source/docs/secrets/pki/index.html.md index bc1f0a2d4..f5acdbda8 100644 --- a/website/source/docs/secrets/pki/index.html.md +++ b/website/source/docs/secrets/pki/index.html.md @@ -382,1435 +382,6 @@ subpath for interactive help output. ## API -### /pki/ca(/pem) -#### GET - -
-
Description
-
- Retrieves the CA certificate *in raw DER-encoded form*. This is a bare - endpoint that does not return a standard Vault data structure. If `/pem` is - added to the endpoint, the CA certificate is returned in PEM format.
-
This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/ca(/pem)`
- -
Parameters
-
- None -
- -
Returns
-
- - ``` - - ``` - -
-
- -### /pki/ca_chain -#### GET - -
-
Description
-
- Retrieves the CA certificate chain, including the CA *in PEM format*. This - is a bare endpoint that does not return a standard Vault data structure. -

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/ca_chain`
- -
Parameters
-
- None -
- -
Returns
-
- - ``` - - ``` - -
-
- -### /pki/cert/ -#### GET - -
-
Description
-
- Retrieves one of a selection of certificates. Valid values: `ca` for the CA - certificate, `crl` for the current CRL, `ca_chain` for the CA trust chain - or a serial number in either hyphen-separated or colon-separated octal - format. This endpoint returns the certificate in PEM formatting in the - `certificate` key of the JSON object.

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/cert/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n..." - } - } - ... - ``` - -
-
- -### /pki/certs/ -#### LIST - -
-
Description
-
- Returns a list of the current certificates by serial number only. -
- -
Method
-
LIST/GET
- -
URL
-
`/pki/certs` (LIST) or `/pki/certs?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id":"", - "renewable":false, - "lease_duration":0, - "data":{ - "keys":[ - "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1", - "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21" - ] - }, - "wrap_info":null, - "warnings":null, - "auth":null - } - ... - ``` - -
-
- -### /pki/config/ca -#### POST - -
-
Description
-
- Allows submitting the CA information for the backend via a PEM file - containing the CA certificate and its private key, concatenated. Not needed - if you are generating a self-signed root certificate, and not used if you - have a signed intermediate CA certificate with a generated key (use the - `/pki/intermediate/set-signed` endpoint for that). _If you have already set - a certificate and key, they will be overridden._

The information - can be provided from a file via a `curl` command similar to the - following:
- - ```text - $ curl \ - -H "X-Vault-Token:06b9d..." \ - -X POST \ - --data "@cabundle.json" \ - http://127.0.0.1:8200/v1/pki/config/ca - ``` - - Note that if you provide the data through the HTTP API it must be - JSON-formatted, with newlines replaced with `\n`, like so: - - ```javascript - { - "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" - } - ``` -
- -
Method
-
POST
- -
URL
-
`/pki/config/ca`
- -
Parameters
-
-
    -
  • - pem_bundle - required - The key and certificate concatenated in PEM format. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/config/crl -#### GET - -
-
Description
-
- Allows getting the duration for which the generated CRL should be marked - valid. -
- -
Method
-
GET
- -
URL
-
`/pki/config/crl`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "expiry": "72h" - }, - "auth": null - } - ``` - -
-
- -#### POST - -
-
Description
-
- Allows setting the duration for which the generated CRL should be marked - valid. -
- -
Method
-
POST
- -
URL
-
`/pki/config/crl`
- -
Parameters
-
-
    -
  • -
  • - expiry - required - The time until expiration. Defaults to `72h`. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/config/urls - -#### GET - -
-
Description
-
- Fetch the URLs to be encoded in generated certificates. -
- -
Method
-
GET
- -
URL
-
`/pki/config/urls`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "issuing_certificates": [, ], - "crl_distribution_points": [, ], - "ocsp_servers": [, ], - }, - "auth": null - } - ``` - -
-
- -#### POST - -
-
Description
-
- Allows setting the issuing certificate endpoints, CRL distribution points, - and OCSP server endpoints that will be encoded into issued certificates. - You can update any of the values at any time without affecting the other - existing values. To remove the values, simply use a blank string as the - parameter. -
- -
Method
-
POST
- -
URL
-
`/pki/config/urls`
- -
Parameters
-
-
    -
  • - issuing_certificates - optional - The URL values for the Issuing Certificate field. -
    • -
  • - crl_distribution_points - optional - The URL values for the CRL Distribution Points field. -
    • -
  • - ocsp_servers - optional - The URL values for the OCSP Servers field. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/crl(/pem) -#### GET - -
-
Description
-
- Retrieves the current CRL *in raw DER-encoded form*. This endpoint - is suitable for usage in the CRL Distribution Points extension in a - CA certificate. This is a bare endpoint that does not return a - standard Vault data structure. If `/pem` is added to the endpoint, - the CRL is returned in PEM format. -

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/crl(/pem)`
- -
Parameters
-
- None -
- -
Returns
-
- - ``` - - ``` - -
-
- -### /pki/crl/rotate -#### GET - -
-
Description
-
- This endpoint forces a rotation of the CRL. This can be used - by administrators to cut the size of the CRL if it contains - a number of certificates that have now expired, but has - not been rotated due to no further certificates being revoked. -
- -
Method
-
GET
- -
URL
-
`/pki/crl/rotate`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "success": true - } - } - ``` - -
-
- -### /pki/intermediate/generate -#### POST - -
-
Description
-
- Generates a new private key and a CSR for signing. If using Vault as a - root, and for many other CAs, the various parameters on the final - certificate are set at signing time and may or may not honor the parameters - set here. _This will overwrite any previously existing CA private key._ If - the path ends with `exported`, the private key will be returned in the - response; if it is `internal` the private key will not be returned and - *cannot be retrieved later*.

This is mostly meant as a helper - function, and not all possible parameters that can be set in a CSR are - supported. -
- -
Method
-
POST
- -
URL
-
`/pki/intermediate/generate/[exported|internal]`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `csr` field will contain the private key (if - exported) and CSR, concatenated. -
    • -
  • - key_type - optional - Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use. Defaults to `2048`. Must be changed to a - valid value if the `key_type` is `ec`. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 21600, - "data": { - "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n", - "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----", - "private_key_type": "rsa" - }, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /pki/intermediate/set-signed -#### POST - -
-
Description
-
- Allows submitting the signed CA certificate corresponding to a private key generated via `/pki/intermediate/generate`. The certificate should be submitted in PEM format; see the documentation for `/pki/config/ca` for some hints on submitting. -
- -
Method
-
POST
- -
URL
-
`/pki/intermediate/set-signed`
- -
Parameters
-
-
    -
  • - certificate - required - The certificate in PEM format. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/issue/ -#### POST - -
-
Description
-
- Generates a new set of credentials (private key and certificate) based on - the role named in the endpoint. The issuing CA certificate is returned as - well, so that only the root CA need be in a client's trust store.

*The private key is _not_ stored. If you do not save the private - key, you will need to request a new certificate.* -
- -
Method
-
POST
- -
URL
-
`/pki/issue/`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. If the CN is allowed by role - policy, it will be issued. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. If any requested names do not match role policy, the - entire request will be denied. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. Only - valid if the role allows IP SANs (which is the default). -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the role's `max_ttl` - value. If not provided, the role's `ttl` value will be used. Note that - the role values default to system values if not explicitly set. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the private key and - certificate, concatenated; if the issuing CA is not a Vault-derived - self-signed root, this will be included as well. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n", - "private_key_type": "rsa", - "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "warnings": "", - "auth": null - } - ``` - -
-
- -### /pki/revoke -#### POST - -
-
Description
-
- Revokes a certificate using its serial number. This is an - alternative option to the standard method of revoking - using Vault lease IDs. A successful revocation will - rotate the CRL. -
- -
Method
-
POST
- -
URL
-
`/pki/revoke`
- -
Parameters
-
-
    -
  • - serial_number - required - The serial number of the certificate to revoke, in - hyphen-separated or colon-separated octal. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "revocation_time": 1433269787 - } - } - ``` -
-
- -### /pki/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. Note that the - `allowed_domains`, `allow_subdomains`, and - `allow_any_name` attributes are additive; between them nearly and across - multiple roles nearly any issuing policy can be accommodated. - `server_flag`, `client_flag`, and `code_signing_flag` are additive as well. - If a client requests a certificate that is not allowed by the CN policy in - the role, the request is denied. -
- -
Method
-
POST
- -
URL
-
`/pki/roles/`
- -
Parameters
-
-
    -
  • - ttl - optional - The Time To Live value provided as a string duration with time suffix. - Hour is the largest suffix. If not set, uses the system default value - or the value of `max_ttl`, whichever is shorter. -
    • -
  • - max_ttl - optional - The maximum Time To Live provided as a string duration with time - suffix. Hour is the largest suffix. If not set, defaults to the system - maximum lease TTL. -
    • -
  • - allow_localhost - optional - If set, clients can request certificates for `localhost` as one of the - requested common names. This is useful for testing and to allow clients - on a single host to talk securely. Defaults to true. -
    • -
  • - allowed_domains - optional - Designates the domains of the role, provided as a comma-separated list. - This is used with the `allow_bare_domains` and `allow_subdomains` - options. There is no default. -
    • -
  • - allow_bare_domains - optional - If set, clients can request certificates matching the value of the - actual domains themselves; e.g. if a configured domain set with - `allowed_domains` is `example.com`, this allows clients to actually - request a certificate containing the name `example.com` as one of the - DNS values on the final certificate. In some scenarios, this can be - considered a security risk. Defaults to false. -
    • -
  • - allow_subdomains - optional - If set, clients can request certificates with CNs that are subdomains - of the CNs allowed by the other role options. _This includes wildcard - subdomains._ For example, an `allowed_domains` value of - `example.com` with this option set to true will allow `foo.example.com` - and `bar.example.com` as well as `*.example.com`. This is redundant - when using the `allow_any_name` option. Defaults to `false`. -
    • -
  • - allow_any_name - optional - If set, clients can request any CN. Useful in some circumstances, but - make sure you understand whether it is appropriate for your - installation before enabling it. Defaults to `false`. -
    • -
  • - enforce_hostnames - optional - If set, only valid host names are allowed for CNs, DNS SANs, and the - host part of email addresses. Defaults to `true`. -
    • -
  • - allow_ip_sans - optional - If set, clients can request IP Subject Alternative Names. No - authorization checking is performed except to verify that the given - values are valid IP addresses. Defaults to `true`. -
  • - server_flag - optional - If set, certificates are flagged for server use. Defaults to `true`. -
    • -
  • - client_flag - optional - If set, certificates are flagged for client use. Defaults to `true`. -
    • -
  • - code_signing_flag - optional - If set, certificates are flagged for code signing use. Defaults to - `false`. -
    • -
  • - email_protection_flag - optional - If set, certificates are flagged for email protection use. Defaults to - `false`. -
    • -
  • - key_type - optional - The type of key to generate for generated private - keys. Currently, `rsa` and `ec` are supported. - Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use for the generated keys. - Defaults to `2048`; this will need to be changed for - `ec` keys. See https://golang.org/pkg/crypto/elliptic/#Curve - for an overview of allowed bit lengths for `ec`. -
    • -
  • - key_usage - optional - This sets the allowed key usage constraint on issued certificates. This - is a comma-separated string; valid values can be found at - https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the - `KeyUsage` part of the value. Values are not case-sensitive. To specify - no key usage constraints, set this to an empty string. Defaults to - `DigitalSignature,KeyAgreement,KeyEncipherment`. -
    • -
  • - use_csr_common_name - optional - If set, when used with the CSR signing endpoint, the common name in the - CSR will be used instead of taken from the JSON data. This does `not` - include any requested SANs in the CSR; use `use_csr_sans` for that. - Defaults to `true`. -
    • -
  • - use_csr_sans - optional - If set, when used with the CSR signing endpoint, the subject alternate - names in the CSR will be used instead of taken from the JSON data. This - does `not` include the common name in the CSR; use - `use_csr_common_name` for that. Defaults to `true`. -
    • -
  • - allow_token_displayname - optional - If set, the display name of the token used when requesting a - certificate will be considered to be a valid host name by the role. - Normal verification behavior applies with respect to subdomains and - wildcards. -
    • -
  • - ou - optional - This sets the OU (OrganizationalUnit) values in the subject field of - issued certificates. This is a comma-separated string. -
    • -
  • - organization - optional - This sets the O (Organization) values in the subject field of issued - certificates. This is a comma-separated string. -
    • -
  • - generate_lease - optional - If set, certificates issued/signed against this role will have Vault - leases attached to them. Defaults to "false". Certificates can be added - to the CRL by `vault revoke ` when certificates are - associated with leases. It can also be done using the `pki/revoke` - endpoint. However, when lease generation is disabled, invoking - `pki/revoke` would be the only way to add the certificates to the CRL. - When large number of certificates are generated with long lifetimes, it - is recommended that lease generation be disabled, as large amount of - leases adversely affect the startup time of Vault. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/pki/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "allow_any_name": false, - "allow_ip_sans": true, - "allow_localhost": true, - "allow_subdomains": false, - "allowed_domains": "example.com,foobar.com", - "client_flag": true, - "code_signing_flag": false, - "key_bits": 2048, - "key_type": "rsa", - "ttl": "6h", - "max_ttl": "12h", - "server_flag": true - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/pki/roles` (LIST) or `/pki/roles?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. Deleting a role does not revoke - certificates previously issued under this role. -
- -
Method
-
DELETE
- -
URL
-
`/pki/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /pki/root/generate -#### POST - -
-
Description
-
- Generates a new self-signed CA certificate and private key. _This will - overwrite any previously-existing private key and certificate._ If the path - ends with `exported`, the private key will be returned in the response; if - it is `internal` the private key will not be returned and *cannot be - retrieved later*. Distribution points use the values set via `config/urls`. -

As with other issued certificates, Vault will automatically - revoke the generated root at the end of its lease period; the CA - certificate will sign its own CRL. -
- -
Method
-
POST
- -
URL
-
`/pki/root/generate/[exported|internal]`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - ttl - optional - Requested Time To Live (after which the certificate will be expired). - This cannot be larger than the mount max (or, if not set, the system - max). -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the private key (if - exported) and certificate, concatenated; if the issuing CA is not a - Vault-derived self-signed root, this will be included as well. -
    • -
  • - key_type - optional - Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use. Defaults to `2048`. Must be changed to a - valid value if the `key_type` is `ec`. -
    • -
  • - max_path_length - optional - If set, the maximum path length to encode in the generated certificate. - Defaults to `-1`, which means no limit. unless the signing certificate - has a maximum path length set, in which case the path length is set to - one less than that of the signing certificate. A limit of `0` means a - literal path length of zero. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/root/sign-intermediate -#### POST - -
-
Description
-
- Uses the configured CA certificate to issue a certificate with appropriate - values for acting as an intermediate CA. Distribution points use the values - set via `config/urls`. Values set in the CSR are ignored unless - `use_csr_values` is set to true, in which case the values from the CSR are - used verbatim. -
- -
Method
-
POST
- -
URL
-
`/pki/root/sign-intermediate`
- -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - ttl - optional - Requested Time To Live (after which the certificate will be expired). - This cannot be larger than the mount max (or, if not set, the system - max). -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
  • - max_path_length - optional - If set, the maximum path length to encode in the generated certificate. - Defaults to `-1`, which means no limit. unless the signing certificate - has a maximum path length set, in which case the path length is set to - one less than that of the signing certificate. A limit of `0` means a - literal path length of zero. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
  • - use_csr_values - optional - If set to `true`, then: 1) Subject information, including names and - alternate names, will be preserved from the CSR rather than using the - values provided in the other parameters to this path; 2) Any key usages - (for instance, non-repudiation) requested in the CSR will be added to - the basic set of key usages used for CA certs signed by this path; 3) - Extensions requested in the CSR will be copied into the issued - certificate. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/sign/ -#### POST - -
-
Description
-
- Signs a new certificate based upon the provided CSR and the supplied - parameters, subject to the restrictions contained in the role named in the - endpoint. The issuing CA certificate is returned as well, so that only the - root CA need be in a client's trust store. -
- -
Method
-
POST
- -
URL
-
`/pki/sign/`
- -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - common_name - required - The requested CN for the certificate. If the CN is allowed by role - policy, it will be issued. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. If any requested names do not match role policy, the - entire request will be denied. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. Only - valid if the role allows IP SANs (which is the default). -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the role's `max_ttl` - value. If not provided, the role's `ttl` value will be used. Note that - the role values default to system values if not explicitly set. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/sign-verbatim -#### POST - -
-
Description
-
- Signs a new certificate based upon the provided CSR. Values are taken - verbatim from the CSR; the _only_ restriction is that this endpoint will - refuse to issue an intermediate CA certificate (see the - `/pki/root/sign-intermediate` endpoint for that functionality.) _This is a - potentially dangerous endpoint and only highly trusted users should - have access._ -
- -
Method
-
POST
- -
URL
-
`/pki/sign-verbatim`
- -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the mount's `max_ttl` - value. If not provided, the mount's `ttl` value will be used, which - defaults to system values if not explicitly set. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"] - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` - -
-
- -### /pki/tidy -#### POST - -
-
Description
-
- Allows tidying up the backend storage and/or CRL by removing certificates - that have expired and are past a certain buffer period beyond their - expiration time. -
- -
Method
-
POST
- -
URL
-
`/pki/tidy`
- -
Parameters
-
-
    -
  • - tidy_cert_store - optional - Whether to tidy up the certificate store. Defaults to `false`. -
    • -
  • - tidy_revocation_list - optional - Whether to tidy up the revocation list (CRL). Defaults to `false`. -
    • -
  • - safety_buffer - optional - A duration (given as an integer number of seconds or a string; defaults - to `72h`) used as a safety buffer to ensure certificates are not - expunged prematurely; as an example, this can keep certificates from - being removed from the CRL that, due to clock skew, might still be - considered valid on other hosts. For a certificate to be expunged, the - time must be after the expiration time of the certificate (according to - the local clock) plus the duration of `safety_buffer`. -
    • -
-
- -
Returns
-
- A `204` status code. -
-
+The PKI secret backend has a full HTTP API. Please see the +[PKI secret backend API](/docs/http/secret/pki/index.html) for more +details. diff --git a/website/source/docs/secrets/postgresql/index.html.md b/website/source/docs/secrets/postgresql/index.html.md index 49d4f8661..d696e3f54 100644 --- a/website/source/docs/secrets/postgresql/index.html.md +++ b/website/source/docs/secrets/postgresql/index.html.md @@ -109,290 +109,6 @@ subpath for interactive help output. ## API -### /postgresql/config/connection -#### POST - -
-
Description
-
- Configures the connection string used to communicate with PostgreSQL. -
- -
Method
-
POST
- -
URL
-
`/postgresql/config/connection`
- -
Parameters
-
-
    -
  • - connection_url - required - The PostgreSQL connection URL or PG style string. e.g. "user=foo host=bar" -
    • -
-
-
-
    -
  • - value - optional - The PostgreSQL connection URL or PG style string. e.g. "user=foo host=bar". Use `connection_url` instead. -
    • -
-
-
-
    -
  • - max_open_connections - optional - Maximum number of open connections to the database. A zero uses the - default value of 2 and a negative value means unlimited. -
    • -
-
-
-
    - max_idle_connections - optional - Maximum number of idle connections to the database. A zero uses the - value of `max_open_connections` and a negative value disables idle - connections. If larger than `max_open_connections` it will be reduced - to be equal. -
-
-
-
    - verify_connection - optional - If set, connection_url is verified by actually connecting to the database. - Defaults to true. -
-
- -
Returns
-
- A `204` response code. -
-
- -### /postgresql/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. - If not configured, leases default to 1 hour. This is a root - protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/postgresql/config/lease`
- -
Parameters
-
-
    -
  • - lease - required - The lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
  • - lease_max - required - The maximum lease value provided as a string duration - with time suffix. Hour is the largest suffix. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /postgresql/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/postgresql/roles/`
- -
Parameters
-
-
    -
  • - sql - required - The SQL statements executed to create and configure the role. Must be - a semicolon-separated string, a base64-encoded semicolon-separated - string, a serialized JSON string array, or a base64-encoded serialized - JSON string array. The '{{name}}', '{{password}}' and '{{expiration}}' - values will be substituted. -
    • -
-
    -
  • - revocation_sql - optional - SQL statements to be executed to revoke a user. Must be a semicolon-separated - string, a base64-encoded semicolon-separated string, a serialized JSON string - array, or a base64-encoded serialized JSON string array. The '{{name}}' value - will be substituted. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/postgresql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "sql": "CREATE USER..." - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/postgresql/roles` (LIST) or `/postgresql/roles/?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/postgresql/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /postgresql/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/postgresql/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "root-1430158508-126", - "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" - } - } - ``` - -
-
- +The PostgreSQL secret backend has a full HTTP API. Please see the +[PostgreSQL secret backend API](/docs/http/secret/postgresql/index.html) for more +details. diff --git a/website/source/docs/secrets/rabbitmq/index.html.md b/website/source/docs/secrets/rabbitmq/index.html.md index ebc36b477..5afa3f6ae 100644 --- a/website/source/docs/secrets/rabbitmq/index.html.md +++ b/website/source/docs/secrets/rabbitmq/index.html.md @@ -110,219 +110,6 @@ subpath for interactive help output. ## API -### /rabbitmq/config/connection -#### POST - -
-
Description
-
- Configures the connection string used to communicate with RabbitMQ. -
- -
Method
-
POST
- -
URL
-
`/rabbitmq/config/connection`
- -
Parameters
-
-
    -
  • - connection_uri - required - The RabbitMQ management connection URI. -
    • -
  • - username - required - The RabbitMQ management administrator username. -
    • -
  • - password - required - The RabbitMQ management administrator password. -
    • -
  • - verify_connection - optional - Whether to verify connection URI, username, and password. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /rabbitmq/config/lease -#### POST - -
-
Description
-
- Configures the lease settings for generated credentials. This is a root - protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/rabbitmq/config/lease`
- -
Parameters
-
-
    -
  • - ttl - optional - The lease ttl provided in seconds. -
    • -
  • - max_ttl - optional - The maximum ttl provided in seconds. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /rabbitmq/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. -
- -
Method
-
POST
- -
URL
-
`/rabbitmq/roles/`
- -
Parameters
-
-
    -
  • - tags - optional - Comma-separated RabbitMQ management tags. -
    • -
  • - vhost - optional - A map of virtual hosts to permissions. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/rabbitmq/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "tags": "", - "vhost": "{\"/\": {\"configure\:".*", \"write\:".*", \"read\": \".*\"}}" - } - } - ``` - -
-
- - -#### DELETE - -
-
Description
-
- Deletes the role definition. -
- -
Method
-
DELETE
- -
URL
-
`/rabbitmq/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /rabbitmq/creds/ -#### GET - -
-
Description
-
- Generates a new set of dynamic credentials based on the named role. -
- -
Method
-
GET
- -
URL
-
`/rabbitmq/creds/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "username": "root-4b95bf47-281d-dcb5-8a60-9594f8056092", - "password": "e1b6c159-ca63-4c6a-3886-6639eae06c30" - } - } - ``` - -
-
+The RabbitMQ secret backend has a full HTTP API. Please see the +[RabbitMQ secret backend API](/docs/http/secret/rabbitmq/index.html) for more +details. diff --git a/website/source/docs/secrets/ssh/index.html.md b/website/source/docs/secrets/ssh/index.html.md index 6de7ba27f..43a2b85ae 100644 --- a/website/source/docs/secrets/ssh/index.html.md +++ b/website/source/docs/secrets/ssh/index.html.md @@ -329,7 +329,7 @@ sign an SSH public key, we simply write to the `sign` end point with that role name: Vault is now configured to create and manage SSH certificates! ```text -$ cat dummy.pub | vault write ssh/sign/example public_key=- +$ cat dummy.pub | vault write ssh/sign/example public_key=- Key Value --- ----- lease_id ssh/sign/example/3c3740ee-6066-55c0-4a5d-82a544a474a3 @@ -352,850 +352,6 @@ username@:~$ ---------------------------------------------------- ## API -### /ssh/keys/ -#### POST - -
-
Description
-
- Creates or updates a named key. -
- -
Method
-
POST
- -
URL
-
`/ssh/keys/`
- -
Parameters
-
-
    -
  • - key - required - (String) - SSH private key with appropriate privileges on remote hosts. -
    • -
-
- -
Returns
-
- A `204` response code. -
- -#### DELETE - -
-
Description
-
- Deletes a named key. -
- -
Method
-
DELETE
- -
URL
-
`/ssh/keys/`
- -
Parameters
-
None
- -
Returns
-
- A `204` response code. -
- -### /ssh/roles/ -#### POST - -
-
Description
-
- Creates or updates a named role. -
- -
Method
-
POST
- -
URL
-
`/ssh/roles/`
- -
Parameters
-
-
    -
  • - key - required for Dynamic Key type, N/A for - OTP type, N/A for CA type - (String) - Name of the registered key in Vault. Before creating the role, use - the `keys/` endpoint to create a named key. -
    • -
  • - admin_user - required for Dynamic Key type, N/A for OTP - type, N/A for CA type - (String) - Admin user at remote host. The shared key being registered should be - for this user and should have root or sudo privileges. Every time a - dynamic credential is generated for a client, Vault uses this admin - username to login to remote host and install the generated - credential. -
    • -
  • - default_user - required for Dynamic Key type, required - for OTP type, optional for CA type - (String) - Default username for which a credential will be generated. When the - endpoint 'creds/' is used without a username, this value will be used - as default username. Its recommended to create individual roles for - each username to ensure absolute isolation between usernames. - - For the CA type, if you wish this to be a valid principal, it must - also be in `allowed_users`. -
    • -
  • - cidr_list - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (String) - Comma separated list of CIDR blocks for which the role is applicable - for. CIDR blocks can belong to more than one role. -
    • -
  • - exclude_cidr_list - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (String) - Comma-separated list of CIDR blocks. IP addresses belonging to these - blocks are not accepted by the role. This is particularly useful when - big CIDR blocks are being used by the role and certain parts need to - be kept out. -
    • -
  • - port - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (Integer) - Port number for SSH connection. The default is '22'. Port number - does not play any role in OTP generation. For the 'otp' backend - type, this is just a way to inform the client about the port number - to use. The port number will be returned to the client by Vault - along with the OTP. -
    • -
  • - key_type - required for all types - (String) - Type of credentials generated by this role. Can be either `otp`, - `dynamic` or `ca`. -
    • -
  • - key_bits - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (Integer) - Length of the RSA dynamic key in bits; can be either 1024 or 2048. - 1024 the default. -
    • -
  • - install_script - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (String) - Script used to install and uninstall public keys in the target - machine. Defaults to the built-in script. -
    • -
  • - allowed_users - optional for all types - (String) - If this option is not specified, client can request for a credential - for any valid user at the remote host, including the admin user. If - only certain usernames are to be allowed, then this list enforces it. - If this field is set, then credentials can only be created for - `default_user` and usernames present in this list. Setting this - option will enable all the users with access this role to fetch - credentials for all other usernames in this list. Use with caution. -
    • -
  • - allowed_domains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - (String) - If this option is not specified, client can request for a signed certificate for any - valid host. If only certain domains are allowed, then this list enforces it. - If this option is explicitly set to `*`, then credentials can be created - for any domain. -
    • -
  • - key_option_specs - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (String) - Comma separated option specification which will be prefixed to RSA - keys in the remote host's authorized_keys file. N.B.: Vault does - not check this string for validity. -
    • -
  • - ttl - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - The Time To Live value provided as a string duration with time suffix. - Hour is the largest suffix. If not set, uses the system default value - or the value of `max_ttl`, whichever is shorter. -
    • -
  • - max_ttl - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - The maximum Time To Live provided as a string duration with time - suffix. Hour is the largest suffix. If not set, defaults to the system - maximum lease TTL. -
    • -
  • - allowed_critical_options - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A comma-separated list of critical options that certificates can have when - signed. To allow any critical options, set this to an empty string. Will - default to allowing any critical options. -
    • -
  • - allowed_extensions - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A comma-separated list of extensions that certificates can have when - signed. To allow any critical options, set this to an empty string. Will - default to allowing any extensions. -
    • -
  • - default_critical_options - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A map of critical options certificates should have if none are provided - when signing. This field takes in key value pairs in JSON format. Note - that these are not restricted by `allowed_critical_options`. Defaults - to none. -
    • -
  • - default_extensions - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A map of extensions certificates should have if none are provided when - signing. This field takes in key value pairs in JSON format. Note that - these are not restricted by `allowed_extensions`. Defaults to none. -
    • -
  • - allow_user_certificates - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, certificates are allowed to be signed for use as a 'user'. - Defaults to false. -
    • -
  • - allow_host_certificates - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, certificates are allowed to be signed for use as a 'host'. - Defaults to false. -
    • -
  • - allow_bare_domains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, host certificates that are requested are allowed to use the base - domains listed in "allowed_users", e.g. "example.com". This - is a separate option as in some cases this can be considered a security - threat. Defaults to false. -
    • -
  • - allow_subdomains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, host certificates that are requested are allowed to use - subdomains of those listed in "allowed_users". Defaults - to false. -
    • -
  • - allow_user_key_ids - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If true, users can override the key ID for a signed certificate with the "key_id" field. - When false, the key ID will always be the token display name. - The key ID is logged by the SSH server and can be useful for auditing. -
    • -
-
- -
Returns
-
- A `204` response code. -
- -#### GET - -
-
Description
-
- Queries a named role. -
- -
Method
-
GET
- -
URL
-
`/ssh/roles/`
- -
Parameters
-
None
- -
Returns
-
Note: these are examples only. For a dynamic key role: - -```json -{ - "admin_user": "username", - "cidr_list": "x.x.x.x/y", - "default_user": "username", - "key": "", - "key_type": "dynamic", - "port": 22 -} -``` - -
- -
For an OTP role: - -```json -{ - "cidr_list": "x.x.x.x/y", - "default_user": "username", - "key_type": "otp", - "port": 22 -} -``` -
-
For a CA role: - -```json -{ - "allow_bare_domains": false, - "allow_host_certificates": true, - "allow_subdomains": false, - "allow_user_key_ids": false, - "allow_user_certificates": true, - "allowed_critical_options": "", - "allowed_extensions": "", - "default_critical_options": {}, - "default_extensions": {}, - "max_ttl": "768h", - "ttl": "4h" -} -``` -
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/ssh/roles` (LIST) or `/ssh/roles?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```json - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a named role. -
- -
Method
-
DELETE
- -
URL
-
`/ssh/roles/`
- -
Parameters
-
None
- -
Returns
-
- A `204` response code. -
- -### /ssh/config/zeroaddress - -#### GET - -
-
Description
-
- Returns the list of configured zero-address roles. -
- -
Method
-
GET
- -
URL
-
`/ssh/config/zeroaddress`
- -
Parameters
-
None
- -
Returns
-
- -```json -{ - "lease_id":"", - "renewable":false, - "lease_duration":0, - "data":{ - "roles":[ - "otp_key_role" - ] - }, - "warnings":null, - "auth":null -} -``` - -
- -#### POST - -
-
Description
-
- Configures zero-address roles. -
- -
Method
-
POST
- -
URL
-
`/ssh/config/zeroaddress`
- -
Parameters
-
-
    -
  • - roles - required - A string containing comma separated list of role names which allows credentials to be requested - for any IP address. CIDR blocks previously registered under these roles will be ignored. -
    • -
-
- -
Returns
-
- A `204` response code. -
- -#### DELETE - -
-
Description
-
- Deletes the zero-address roles configuration. -
- -
Method
-
DELETE
- -
URL
-
`/ssh/config/zeroaddress`
- -
Parameters
-
None
- -
Returns
-
- A `204` response code. -
- - -### /ssh/creds/ -#### POST - -
-
Description
-
- Creates credentials for a specific username and IP with the - parameters defined in the given role. -
- -
Method
-
POST
- -
URL
-
`/ssh/creds/`
- -
Parameters
-
-
    -
  • - username - optional - (String) - Username on the remote host. -
    • -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
- -
Returns
-
For a dynamic key role: - -```json -{ - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "admin_user": "rajanadar", - "allowed_users": "", - "cidr_list": "x.x.x.x/y", - "default_user": "rajanadar", - "exclude_cidr_list": "x.x.x.x/y", - "install_script": "pretty_large_script", - "key": "5d9ee6a1-c787-47a9-9738-da243f4f69bf", - "key_bits": 1024, - "key_option_specs": "", - "key_type": "dynamic", - "port": 22 - }, - "warnings": null, - "auth": null -} -``` - -
- -
For an OTP role: - -```json -{ - "lease_id": "sshs/creds/c3c2e60c-5a48-415a-9d5a-a41e0e6cdec5/3ee6ad28-383f-d482-2427-70498eba4d96", - "renewable": false, - "lease_duration": 2764800, - "data": { - "ip": "127.0.0.1", - "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2", - "key_type": "otp", - "port": 22, - "username": "rajanadar" - }, - "warnings": null, - "auth": null -} -``` -
- - -### /ssh/lookup -#### POST - -
-
Description
-
- Lists all of the roles with which the given IP is associated. -
- -
Method
-
POST
- -
URL
-
`/ssh/lookup`
- -
Parameters
-
-
    -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
- -
Returns
-
An array of roles as a secret structure. - -```json -{ - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "roles": ["fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"] - }, - "warnings": null, - "auth": null -} -``` -
- -### /ssh/verify -#### POST - -
-
Description
-
- Verifies if the given OTP is valid. This is an unauthenticated - endpoint. -
- -
Method
-
POST
- -
URL
-
`/ssh/verify`
- -
Parameters
-
-
    -
  • - otp - required - (String) - One-Time-Key that needs to be validated. -
    • -
-
- -
Returns
-
A `200` response code for a valid OTP. - -```json -{ - "lease_id":"", - "renewable":false, - "lease_duration":0, - "data":{ - "ip":"127.0.0.1", - "username":"rajanadar" - }, - "warnings":null, - "auth":null -} -``` - -
- -
A `400` BadRequest response code with 'OTP not found' message, for an invalid OTP.
- -### /ssh/config/ca -#### POST - -
-
Description
-
- Allows submitting the CA information for the backend via an SSH key pair. - _If you have already set a certificate and key, they will be overridden._

-
- -
Method
-
POST
- -
URL
-
`/ssh/config/ca`
- -
Parameters
-
-
    -
  • - private_key - optional - The private key part the SSH CA key pair; required if generate_signing_key is false. -
    • -
  • - public_key - optional - The public key part of the SSH CA key pair; required if generate_signing_key is false. -
    • -
  • - generate_signing_key - optional - Generate the signing key pair interally if true, otherwise use the private_key and public_key fields. - The generated public key will be returned so you can add it to your configuration. -
    • -
-
- -
Returns
-
- A `204` response code. And if generate_signing_key was true: -
-
- ```json - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "public_key": "ssh-rsa AAAAHHNzaC1y...\n" - }, - "warnings": null - } - ``` -
-
- -#### GET - -
-
Description
-
- Reads the configured/generated public key. -
- -
Method
-
GET
- -
URL
-
`/ssh/config/ca`
- -
Parameters
-
None
- -
Returns
-
- ```json - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "public_key": "ssh-rsa AAAAHHNzaC1y...\n" - }, - "warnings": null - } - ``` -
-
- -### /ssh/sign -#### POST - -
-
Description
-
- Signs an SSH public key based on the supplied parameters, subject to the - restrictions contained in the role named in the endpoint. -
- -
Method
-
POST
- -
URL
-
`/ssh/sign/`
- -
Parameters
-
-
    -
  • - public_key - required - SSH public key that should be signed. -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the role's `max_ttl` - value. If not provided, the role's `ttl` value will be used. Note that - the role values default to system values if not explicitly set. -
    • -
  • - valid_principals - optional - Valid principals, either usernames or hostnames, that the certificate - should be signed for. Defaults to none. -
    • -
  • - cert_type - optional - Type of certificate to be created; either "user" or "host". Defaults to - "user". -
    • -
  • - key_id - optional - Key id that the created certificate should have. If not specified, - the display name of the token will be used. -
    • -
  • - critical_options - optional - A map of the critical options that the certificate should be signed for. - Defaults to none. -
    • -
  • - extensions - optional - A map of the extensions that the certificate should be signed for. - Defaults to none -
    • -
-
- -
Returns
-
- - ```json - { - "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993", - "renewable": false, - "lease_duration": 21600, - "data": { - "serial_number": "f65ed2fd21443d5c", - "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n" - }, - "auth": null - } - ``` - -
-
+The SSH secret backend has a full HTTP API. Please see the +[SSH secret backend API](/docs/http/secret/ssh/index.html) for more +details. diff --git a/website/source/docs/secrets/transit/index.html.md b/website/source/docs/secrets/transit/index.html.md index ea9838427..422434a59 100644 --- a/website/source/docs/secrets/transit/index.html.md +++ b/website/source/docs/secrets/transit/index.html.md @@ -98,7 +98,7 @@ supports_derivation true supports_encryption true supports_signing false type aes256-gcm96 -```` +``` Now, if we wanted to encrypt a piece of plain text, we use the encrypt endpoint using our named key: @@ -131,925 +131,6 @@ only encrypt or decrypt using the named keys they need access to. ## API -### /transit/keys/ -#### POST - -
-
Description
-
- Creates a new named encryption key of the specified type. The values set - here cannot be changed after key creation. -
- -
Method
-
POST
- -
URL
-
`/transit/keys/`
- -
Parameters
-
-
    -
  • - type - required - The type of key to create. The currently-supported types are: -
      -
    • `aes256-gcm96`: AES-256 wrapped with GCM using a 12-byte nonce size (symmetric)
      • -
    • `ecdsa-p256`: ECDSA using the P-256 elliptic curve (asymmetric)
      • -
    - Defaults to `aes256-gcm96`. -
    • -
  • - derived - optional - Boolean flag indicating if key derivation MUST be used. If enabled, all - encrypt/decrypt requests to this named key must provide a context - which is used for key derivation. Defaults to false. -
    • -
  • - convergent_encryption - optional - If set, the key will support convergent encryption, where the same - plaintext creates the same ciphertext. This requires _derived_ to be - set to `true`. When enabled, each - encryption(/decryption/rewrap/datakey) operation will derive a `nonce` - value rather than randomly generate it. Note that while this is useful - for particular situations, all nonce values used with a given context - value **must be unique** or it will compromise the security of your - key, and the key space for nonces is 96 bit -- not as large as the AES - key itself. Defaults to false. -
    • -
  • - exportable - optional - Boolean flag indicating if the key is exportable. Defaults to false. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Returns information about a named encryption key. The `keys` object shows - the creation time of each key version; the values are not the keys - themselves. Depending on the type of key, different information may be - returned, e.g. an asymmetric key will return its public key in a standard - format for the type. -
- -
Method
-
GET
- -
URL
-
`/transit/keys/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "type": "aes256-gcm96", - "deletion_allowed": false, - "derived": false, - "exportable": false, - "keys": { - "1": 1442851412 - }, - "min_decryption_version": 0, - "name": "foo", - "supports_encryption": true, - "supports_decryption": true, - "supports_derivation": true, - "supports_signing": false - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of keys. Only the key names are returned. -
- -
Method
-
LIST/GET
- -
URL
-
`/transit/keys` (LIST) or `/transit/keys?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "keys": ["foo", "bar"] - }, - "lease_duration": 0, - "lease_id": "", - "renewable": false - } - ``` - -
-
- -#### DELETE - -
-
Description
-
- Deletes a named encryption key. - It will no longer be possible to decrypt any data encrypted with the - named key. Because this is a potentially catastrophic operation, the - `deletion_allowed` tunable must be set in the key's `/config` endpoint. -
- -
Method
-
DELETE
- -
URL
-
`/transit/keys/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /transit/keys/config -#### POST - -
-
Description
-
- Allows tuning configuration values for a given key. (These values are - returned during a read operation on the named key.) -
- -
Method
-
POST
- -
URL
-
`/transit/keys//config`
- -
Parameters
-
-
    -
  • - min_decryption_version - optional - The minimum version of ciphertext allowed to be decrypted. Adjusting - this as part of a key rotation policy can prevent old copies of - ciphertext from being decrypted, should they fall into the wrong hands. - For signatures, this value controls the minimum version of signature - that can be verified against. For HMACs, this controls the minimum - version of a key allowed to be used as the key for the HMAC function. - Defaults to 0. -
    • -
  • - deletion_allowed - optional - When set, the key is allowed to be deleted. Defaults to false. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /transit/keys/rotate/ -#### POST - -
-
Description
-
- Rotates the version of the named key. After rotation, new plaintext - requests will be encrypted with the new version of the key. To upgrade - ciphertext to be encrypted with the latest version of the key, use the - `rewrap` endpoint. This is only supported with keys that support encryption - and decryption operations. -
- -
Method
-
POST
- -
URL
-
`/transit/keys//rotate`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -### /transit/export/encryption-key/\(/\) -### /transit/export/signing-key/\(/\) -### /transit/export/hmac-key/\(/\) -#### GET - -
-
Description
-
- Returns the named key. The `keys` object shows the value of the key for - each version. If `version` is specified, the specific version will be - returned. If `latest` is provided as the version, the current key will be - provided. Depending on the type of key, different information may be - returned. The key must be exportable to support this operation and the - version must still be valid. -
- -
Method
-
GET
- -
URL
-
`/transit/export///`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "name": "foo", - "keys": { - "1": "eyXYGHbTmugUJn6EtYD/yVEoF6pCxm4R/cMEutUm3MY=", - "2": "Euzymqx6iXjS3/NuGKDCiM2Ev6wdhnU+rBiKnJ7YpHE=" - } - } - } - ``` - -
-
- -### /transit/encrypt/ -#### POST - -
-
Description
-
- Encrypts the provided plaintext using the named key. Currently, this only - supports symmetric keys. This path supports the `create` and `update` - policy capabilities as follows: if the user has the `create` capability for - this endpoint in their policies, and the key does not exist, it will be - upserted with default values (whether the key requires derivation depends - on whether the context parameter is empty or not). If the user only has - `update` capability and the key does not exist, an error will be returned. -
- -
Method
-
POST
- -
URL
-
`/transit/encrypt/`
- -
Parameters
-
-
    -
  • - plaintext - required - Base64 encoded plaintext value to be encrypted. -
    • -
-
    -
  • - context - optional - Base64 encoded context for key derivation. Required if key derivation - is enabled. -
    • -
-
    -
  • - nonce - optional - Base64 encoded nonce value. Must be provided if convergent encryption is - enabled for this key and the key was generated with Vault 0.6.1. Not required - for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long - and the user must ensure that for any given context (and thus, any given - encryption key) this nonce value is **never reused**. -
    • -
-
    -
  • - batch_input - optional - List of items to be encrypted in a single batch. When - this parameter is set, if the parameters 'plaintext', 'context' and - 'nonce' are also set, they will be ignored. Format for the input - goes like this: - -```javascript -[ - { - "context": "c2FtcGxlY29udGV4dA==", - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" - }, - { - "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveA==" - }, - ... -] -``` - -
    • -
-
    -
  • - type - optional - This parameter is required when encryption key is expected to be created. - When performing an upsert operation, the type of key to create. Currently, - "aes256-gcm96" (symmetric) is the only type supported. Defaults to - "aes256-gcm96". -
    • -
-
    -
  • - convergent_encryption - optional - This parameter will only be used when a key is expected to be created. Whether - to support convergent encryption. This is only supported when using a key with - key derivation enabled and will require all requests to carry both a context - and 96-bit (12-byte) nonce. The given nonce will be used in place of a randomly - generated nonce. As a result, when the same context and nonce are supplied, the - same ciphertext is generated. It is *very important* when using this mode that - you ensure that all nonces are unique for a given context. Failing to do so - will severely impact the ciphertext's security. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "ciphertext": "vault:v1:abcdefgh" - } - } - ``` - -
-
- -### /transit/decrypt/ -#### POST - -
-
Description
-
- Decrypts the provided ciphertext using the named key. Currently, this only - supports symmetric keys. -
- -
Method
-
POST
- -
URL
-
`/transit/decrypt/`
- -
Parameters
-
-
    -
  • - ciphertext - required - The ciphertext to decrypt, provided as returned by encrypt. -
    • -
  • - context - optional - Base64 encoded context for key derivation. Required if key derivation is - enabled. -
    • -
  • - nonce - optional - Base64 encoded nonce value used during encryption. Must be provided if - convergent encryption is enabled for this key and the key was generated with - Vault 0.6.1. Not required for keys created in 0.6.2+. -
    • -
-
    -
  • - batch_input - optional - List of items to be decrypted in a single batch. When this parameter is - set, if the parameters 'ciphertext', 'context' and 'nonce' are also - set, they will be ignored. Format for the input goes like this: - -```javascript -[ - { - "context": "c2FtcGxlY29udGV4dA==", - "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" - }, - { - "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", - "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" - }, - ... -] -``` - -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/rewrap/ -#### POST - -
-
Description
-
- Rewrap the provided ciphertext using the latest version of the named key. - Because this never returns plaintext, it is possible to delegate this - functionality to untrusted users or scripts. -
- -
Method
-
POST
- -
URL
-
`/transit/rewrap/`
- -
Parameters
-
-
    -
  • - ciphertext - required - The ciphertext to decrypt, provided as returned by encrypt. -
    • -
  • - context - optional - Base64 encoded context for key derivation. Required for derived keys. -
    • -
  • - nonce - optional - The nonce value used during encryption, provided as base64 encoded. - Must be provided if convergent encryption is enabled for this key and - the key was created with Vault 0.6.1. Not required for keys created in - 0.6.2+. -
    • -
  • - batch_input - optional - List of items to be rewrapped in a single batch. When this parameter is - set, if the parameters 'ciphertext', 'context' and 'nonce' are also - set, they will be ignored. Format for the input goes like this: - -```javascript -[ - { - "context": "c2FtcGxlY29udGV4dA==", - "ciphertext": "vault:v1:/DupSiSbX/ATkGmKAmhqD0tvukByrx6gmps7dVI=" - }, - { - "context": "YW5vdGhlcnNhbXBsZWNvbnRleHQ=", - "ciphertext": "vault:v1:XjsPWPjqPrBi1N2Ms2s1QM798YyFWnO4TR4lsFA=" - }, - ... -] -``` - -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "ciphertext": "vault:v2:abcdefgh" - } - } - ``` - -
-
- -### /transit/datakey/ -#### POST - -
-
Description
-
- Generate a new high-entropy key and the value encrypted with the named - key. Optionally return the plaintext of the key as well. Whether plaintext - is returned depends on the path; as a result, you can use Vault ACL - policies to control whether a user is allowed to retrieve the plaintext - value of a key. This is useful if you want an untrusted user or operation - to generate keys that are then made available to trusted users. -
- -
Method
-
POST
- -
URL
-
`/transit/datakey//`
- -
Parameters
-
-
    -
  • - plaintext|wrapped (path parameter) - required - If `plaintext`, the plaintext key will be returned along with the - ciphertext. If `wrapped`, only the ciphertext value will be returned. -
    • -
  • - context - optional - The key derivation context, provided as a base64-encoded string. - Must be provided if derivation is enabled. -
    • -
  • - nonce - optional - The nonce value, provided as base64 encoded. Must be provided if - convergent encryption is enabled for this key and the key was generated - with Vault 0.6.1. Not required for keys created in 0.6.2+. The value - must be exactly 96 bits (12 bytes) long and the user must ensure that - for any given context (and thus, any given encryption key) this nonce - value is **never reused**. -
    • -
  • - bits - optional - The number of bits in the desired key. Can be 128, 256, or 512; if not - given, defaults to 256. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "plaintext": "dGhlIHF1aWNrIGJyb3duIGZveAo=", - "ciphertext": "vault:v1:abcdefgh" - } - } - ``` - -
-
- -### /transit/random -#### POST - -
-
Description
-
- Return high-quality random bytes of the specified length. -
- -
Method
-
POST
- -
URL
-
`/transit/random(/)`
- -
Parameters
-
-
    -
  • - bytes - optional - The number of bytes to return. Defaults to 32 (256 bits). This value - can be specified either in the request body, or as a part of the URL - with a format like `/transit/random/48`. -
    • -
  • - format - optional - The output encoding; can be either `hex` or `base64`. Defaults to - `base64`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "random_bytes": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/hash -#### POST - -
-
Description
-
- Returns the hash of given data using the specified algorithm. The algorithm - can be specified as part of the URL or given via a parameter; the URL value - takes precedence if both are set. -
- -
Method
-
POST
- -
URL
-
`/transit/hash(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
  • - format - optional - The output encoding; can be either `hex` or `base64`. Defaults to - `hex`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "sum": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/hmac/ -#### POST - -
-
Description
-
- Returns the digest of given data using the specified hash algorithm and the - named key. The key can be of any type supported by `transit`; the raw key - will be marshalled into bytes to be used for the HMAC function. If the key - is of a type that supports rotation, the latest (current) version will be - used. -
- -
Method
-
POST
- -
URL
-
`/transit/hmac/(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
  • - format - optional - The output encoding; can be either `hex` or `base64`. Defaults to - `hex`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "hmac": "dGhlIHF1aWNrIGJyb3duIGZveAo=" - } - } - ``` - -
-
- -### /transit/sign/ -#### POST - -
-
Description
-
- Returns the cryptographic signature of the given data using the named key - and the specified hash algorithm. The key must be of a type that supports - signing. -
- -
Method
-
POST
- -
URL
-
`/transit/sign/(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "signature": "vault:v1:MEUCIQCyb869d7KWuA0hBM9b5NJrmWzMW3/pT+0XYCM9VmGR+QIgWWF6ufi4OS2xo1eS2V5IeJQfsi59qeMWtgX0LipxEHI=" - } - } - ``` - -
-
- -### /transit/verify/ -#### POST - -
-
Description
-
- Returns whether the provided signature is valid for the given data. -
- -
Method
-
POST
- -
URL
-
`/transit/verify/(/)`
- -
Parameters
-
-
    -
  • - input - required - The base64-encoded input data. -
    • -
  • - signature - required - The signature output from the `/transit/sign` function. Either this must be supplied or `hmac` must be supplied. -
    • -
  • - hmac - required - The signature output from the `/transit/hmac` function. Either this must be supplied or `signature` must be supplied. -
    • -
  • - algorithm - optional - The hash algorithm to use. This can also be specified in the URL. - Currently-supported algorithms are: -
      -
    • `sha2-224`
      • -
    • `sha2-256`
      • -
    • `sha2-384`
      • -
    • `sha2-512`
      • -
    - Defaults to `sha2-256`. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "valid": true - } - } - ``` - -
-
+The Transit secret backend has a full HTTP API. Please see the +[Transit secret backend API](/docs/http/secret/transit/index.html) for more +details. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 39e43e760..053db3a7c 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -154,10 +154,6 @@ - > - API & Libraries - -
> @@ -289,6 +285,10 @@
+ > + API & Libraries + + > Guides From b078963ab22f55f80aaad1c6642136f176380f34 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Wed, 15 Mar 2017 23:51:46 -0700 Subject: [PATCH 07/17] Hide auth backends for now The migration is getting too large, so we'll tackle this move in another PR --- website/source/layouts/http.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index 31fd6fe7a..281c78d1b 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -11,9 +11,9 @@
- > + > Secret Backends From e473ee99a8fd7c752773204f63af5c2109f2ea8b Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 00:21:49 -0700 Subject: [PATCH 08/17] Fix TODOs --- website/source/docs/http/secret/aws/index.html.md | 2 +- website/source/docs/http/secret/cassandra/index.html.md | 2 +- website/source/docs/http/secret/consul/index.html.md | 2 +- website/source/docs/http/secret/cubbyhole/index.html.md | 2 +- website/source/docs/http/secret/generic/index.html.md | 2 +- website/source/docs/http/secret/mongodb/index.html.md | 2 +- website/source/docs/http/secret/mssql/index.html.md | 2 +- website/source/docs/http/secret/mysql/index.html.md | 2 +- website/source/docs/http/secret/pki/index.html.md | 2 +- website/source/docs/http/secret/postgresql/index.html.md | 2 +- website/source/docs/http/secret/rabbitmq/index.html.md | 2 +- website/source/docs/http/secret/ssh/index.html.md | 2 +- website/source/docs/http/secret/transit/index.html.md | 2 +- 13 files changed, 13 insertions(+), 13 deletions(-) diff --git a/website/source/docs/http/secret/aws/index.html.md b/website/source/docs/http/secret/aws/index.html.md index d130c5f57..aa7c10151 100644 --- a/website/source/docs/http/secret/aws/index.html.md +++ b/website/source/docs/http/secret/aws/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "HTTP API" sidebar_current: "docs-http-secret-aws" description: |- - TODO + This is the API documentation for the Vault AWS secret backend. --- # AWS Secret Backend HTTP API diff --git a/website/source/docs/http/secret/cassandra/index.html.md b/website/source/docs/http/secret/cassandra/index.html.md index a9f502ac5..9d6a79be7 100644 --- a/website/source/docs/http/secret/cassandra/index.html.md +++ b/website/source/docs/http/secret/cassandra/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "Cassandra Secret Backend - HTTP API" sidebar_current: "docs-http-secret-cassandra" description: |- - TODO + This is the API documentation for the Vault Cassandra secret backend. --- # Cassandra Secret Backend HTTP API diff --git a/website/source/docs/http/secret/consul/index.html.md b/website/source/docs/http/secret/consul/index.html.md index 674c9fe20..33a0068c7 100644 --- a/website/source/docs/http/secret/consul/index.html.md +++ b/website/source/docs/http/secret/consul/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "Consul Secret Backend - HTTP API" sidebar_current: "docs-http-secret-consul" description: |- - TODO + This is the API documentation for the Vault Consul secret backend. --- # Consul Secret Backend HTTP API diff --git a/website/source/docs/http/secret/cubbyhole/index.html.md b/website/source/docs/http/secret/cubbyhole/index.html.md index 77b31ca4e..9fe4f88f6 100644 --- a/website/source/docs/http/secret/cubbyhole/index.html.md +++ b/website/source/docs/http/secret/cubbyhole/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "Cubbyhole Secret Backend - HTTP API" sidebar_current: "docs-http-secret-cubbyhole" description: |- - TODO + This is the API documentation for the Vault Cubbyhole secret backend. --- # Cubbyhole Secret Backend HTTP API diff --git a/website/source/docs/http/secret/generic/index.html.md b/website/source/docs/http/secret/generic/index.html.md index 6e1b33ea9..18299a77e 100644 --- a/website/source/docs/http/secret/generic/index.html.md +++ b/website/source/docs/http/secret/generic/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "Generic Secret Backend - HTTP API" sidebar_current: "docs-http-secret-generic" description: |- - TODO + This is the API documentation for the Vault Generic secret backend. --- # Generic Secret Backend HTTP API diff --git a/website/source/docs/http/secret/mongodb/index.html.md b/website/source/docs/http/secret/mongodb/index.html.md index 4ddceee92..9a82e3932 100644 --- a/website/source/docs/http/secret/mongodb/index.html.md +++ b/website/source/docs/http/secret/mongodb/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "MongoDB Secret Backend - HTTP API" sidebar_current: "docs-http-secret-mongodb" description: |- - TODO + This is the API documentation for the Vault MongoDB secret backend. --- # MongoDB Secret Backend HTTP API diff --git a/website/source/docs/http/secret/mssql/index.html.md b/website/source/docs/http/secret/mssql/index.html.md index 6099ff027..22229d2c4 100644 --- a/website/source/docs/http/secret/mssql/index.html.md +++ b/website/source/docs/http/secret/mssql/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "MSSQL Secret Backend - HTTP API" sidebar_current: "docs-http-secret-mssql" description: |- - TODO + This is the API documentation for the Vault MSSQL secret backend. --- # MSSQL Secret Backend HTTP API diff --git a/website/source/docs/http/secret/mysql/index.html.md b/website/source/docs/http/secret/mysql/index.html.md index c543ddb03..4fcd16581 100644 --- a/website/source/docs/http/secret/mysql/index.html.md +++ b/website/source/docs/http/secret/mysql/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "MySQL Secret Backend - HTTP API" sidebar_current: "docs-http-secret-mysql" description: |- - TODO + This is the API documentation for the Vault MySQL secret backend. --- # MySQL Secret Backend HTTP API diff --git a/website/source/docs/http/secret/pki/index.html.md b/website/source/docs/http/secret/pki/index.html.md index df9ae26f4..caafae872 100644 --- a/website/source/docs/http/secret/pki/index.html.md +++ b/website/source/docs/http/secret/pki/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "PKI Secret Backend - HTTP API" sidebar_current: "docs-http-secret-pki" description: |- - TODO + This is the API documentation for the Vault PKI secret backend. --- # PKI Secret Backend HTTP API diff --git a/website/source/docs/http/secret/postgresql/index.html.md b/website/source/docs/http/secret/postgresql/index.html.md index 6b032f6b1..995e88b12 100644 --- a/website/source/docs/http/secret/postgresql/index.html.md +++ b/website/source/docs/http/secret/postgresql/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "PostgreSQL Secret Backend - HTTP API" sidebar_current: "docs-http-secret-postgresql" description: |- - TODO + This is the API documentation for the Vault PostgreSQL secret backend. --- # PostgreSQL Secret Backend HTTP API diff --git a/website/source/docs/http/secret/rabbitmq/index.html.md b/website/source/docs/http/secret/rabbitmq/index.html.md index bf642f911..cc461368b 100644 --- a/website/source/docs/http/secret/rabbitmq/index.html.md +++ b/website/source/docs/http/secret/rabbitmq/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "RabbitMQ Secret Backend - HTTP API" sidebar_current: "docs-http-secret-rabbitmq" description: |- - TODO + This is the API documentation for the Vault RabbitMQ secret backend. --- # RabbitMQ Secret Backend HTTP API diff --git a/website/source/docs/http/secret/ssh/index.html.md b/website/source/docs/http/secret/ssh/index.html.md index df530de10..9563ca542 100644 --- a/website/source/docs/http/secret/ssh/index.html.md +++ b/website/source/docs/http/secret/ssh/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "SSH Secret Backend - HTTP API" sidebar_current: "docs-http-secret-ssh" description: |- - TODO + This is the API documentation for the Vault SSH secret backend. --- # SSH Secret Backend HTTP API diff --git a/website/source/docs/http/secret/transit/index.html.md b/website/source/docs/http/secret/transit/index.html.md index 00b3a65c8..5f52ee46f 100644 --- a/website/source/docs/http/secret/transit/index.html.md +++ b/website/source/docs/http/secret/transit/index.html.md @@ -3,7 +3,7 @@ layout: "http" page_title: "Transit Secret Backend - HTTP API" sidebar_current: "docs-http-secret-transit" description: |- - TODO + This is the API documentation for the Vault Transit secret backend. --- # Transit Secret Backend HTTP API From e86465c13ba2ecb080e0c222c3d3f357c594d89d Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 01:04:02 -0700 Subject: [PATCH 09/17] Add SSH --- .../source/docs/http/secret/pki/index.html.md | 5 - .../source/docs/http/secret/ssh/index.html.md | 1184 ++++++++--------- 2 files changed, 535 insertions(+), 654 deletions(-) diff --git a/website/source/docs/http/secret/pki/index.html.md b/website/source/docs/http/secret/pki/index.html.md index caafae872..642b4e805 100644 --- a/website/source/docs/http/secret/pki/index.html.md +++ b/website/source/docs/http/secret/pki/index.html.md @@ -1449,8 +1449,3 @@ update your API calls accordingly. A `204` status code.
-======= -The PKI secret backend has a full HTTP API. Please see the -[PKI secret backend API](/docs/http/secret/pki/index.html) for more -details. ->>>>>>> e54ffcd1... Break out API documentation for secret backends diff --git a/website/source/docs/http/secret/ssh/index.html.md b/website/source/docs/http/secret/ssh/index.html.md index 9563ca542..d7fe1dcbd 100644 --- a/website/source/docs/http/secret/ssh/index.html.md +++ b/website/source/docs/http/secret/ssh/index.html.md @@ -16,300 +16,222 @@ This documentation assumes the SSH backend is mounted at the `/ssh` path in Vault. Since it is possible to mount secret backends at any location, please update your API calls accordingly. -### /ssh/keys/ -#### POST +## Create/Update Key -
-
Description
-
- Creates or updates a named key. -
+This endpoint creates or updates a named key. -
Method
-
POST
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/keys/:name` | `204 (empty body)` | -
URL
-
`/ssh/keys/`
+### Parameters -
Parameters
-
-
    -
  • - key - required - (String) - SSH private key with appropriate privileges on remote hosts. -
    • -
-
+- `name` `(string: )` – Specifies the name of the key to create. This + is part of the request URL. -
Returns
-
- A `204` response code. -
+- `key` `(string: )` – Specifies an SSH private key with appropriate + privileges on remote hosts. -#### DELETE +### Sample Payload -
-
Description
-
- Deletes a named key. -
+```json +{ + "key": "..." +} +``` -
Method
-
DELETE
+### Sample Request -
URL
-
`/ssh/keys/`
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/keys/my-key +``` -
Parameters
-
None
+## Delete Key -
Returns
-
- A `204` response code. -
+This endpoint deletes a named key. -### /ssh/roles/ -#### POST +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/ssh/keys/:name` | `204 (empty body)` | -
-
Description
-
- Creates or updates a named role. -
-
Method
-
POST
+### Parameters -
URL
-
`/ssh/roles/`
+- `name` `(string: )` – Specifies the name of the key to delete. This + is part of the request URL. -
Parameters
-
-
    -
  • - key - required for Dynamic Key type, N/A for - OTP type, N/A for CA type - (String) - Name of the registered key in Vault. Before creating the role, use - the `keys/` endpoint to create a named key. -
    • -
  • - admin_user - required for Dynamic Key type, N/A for OTP - type, N/A for CA type - (String) - Admin user at remote host. The shared key being registered should be - for this user and should have root or sudo privileges. Every time a - dynamic credential is generated for a client, Vault uses this admin - username to login to remote host and install the generated - credential. -
    • -
  • - default_user - required for Dynamic Key type, required - for OTP type, optional for CA type - (String) - Default username for which a credential will be generated. When the - endpoint 'creds/' is used without a username, this value will be used - as default username. Its recommended to create individual roles for - each username to ensure absolute isolation between usernames. +### Sample Request - For the CA type, if you wish this to be a valid principal, it must - also be in `allowed_users`. -
    • -
  • - cidr_list - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (String) - Comma separated list of CIDR blocks for which the role is applicable - for. CIDR blocks can belong to more than one role. -
    • -
  • - exclude_cidr_list - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (String) - Comma-separated list of CIDR blocks. IP addresses belonging to these - blocks are not accepted by the role. This is particularly useful when - big CIDR blocks are being used by the role and certain parts need to - be kept out. -
    • -
  • - port - optional for Dynamic Key type, optional for - OTP type, N/A for CA type - (Integer) - Port number for SSH connection. The default is '22'. Port number - does not play any role in OTP generation. For the 'otp' backend - type, this is just a way to inform the client about the port number - to use. The port number will be returned to the client by Vault - along with the OTP. -
    • -
  • - key_type - required for all types - (String) - Type of credentials generated by this role. Can be either `otp`, - `dynamic` or `ca`. -
    • -
  • - key_bits - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (Integer) - Length of the RSA dynamic key in bits; can be either 1024 or 2048. - 1024 the default. -
    • -
  • - install_script - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (String) - Script used to install and uninstall public keys in the target - machine. Defaults to the built-in script. -
    • -
  • - allowed_users - optional for all types - (String) - If this option is not specified, client can request for a credential - for any valid user at the remote host, including the admin user. If - only certain usernames are to be allowed, then this list enforces it. - If this field is set, then credentials can only be created for - `default_user` and usernames present in this list. Setting this - option will enable all the users with access this role to fetch - credentials for all other usernames in this list. Use with caution. -
    • -
  • - allowed_domains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - (String) - If this option is not specified, client can request for a signed certificate for any - valid host. If only certain domains are allowed, then this list enforces it. - If this option is explicitly set to `*`, then credentials can be created - for any domain. -
    • -
  • - key_option_specs - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (String) - Comma separated option specification which will be prefixed to RSA - keys in the remote host's authorized_keys file. N.B.: Vault does - not check this string for validity. -
    • -
  • - ttl - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - The Time To Live value provided as a string duration with time suffix. - Hour is the largest suffix. If not set, uses the system default value - or the value of `max_ttl`, whichever is shorter. -
    • -
  • - max_ttl - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - The maximum Time To Live provided as a string duration with time - suffix. Hour is the largest suffix. If not set, defaults to the system - maximum lease TTL. -
    • -
  • - allowed_critical_options - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A comma-separated list of critical options that certificates can have when - signed. To allow any critical options, set this to an empty string. Will - default to allowing any critical options. -
    • -
  • - allowed_extensions - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A comma-separated list of extensions that certificates can have when - signed. To allow any critical options, set this to an empty string. Will - default to allowing any extensions. -
    • -
  • - default_critical_options - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A map of critical options certificates should have if none are provided - when signing. This field takes in key value pairs in JSON format. Note - that these are not restricted by `allowed_critical_options`. Defaults - to none. -
    • -
  • - default_extensions - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - A map of extensions certificates should have if none are provided when - signing. This field takes in key value pairs in JSON format. Note that - these are not restricted by `allowed_extensions`. Defaults to none. -
    • -
  • - allow_user_certificates - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, certificates are allowed to be signed for use as a 'user'. - Defaults to false. -
    • -
  • - allow_host_certificates - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, certificates are allowed to be signed for use as a 'host'. - Defaults to false. -
    • -
  • - allow_bare_domains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, host certificates that are requested are allowed to use the base - domains listed in "allowed_users", e.g. "example.com". This - is a separate option as in some cases this can be considered a security - threat. Defaults to false. -
    • -
  • - allow_subdomains - N/A for Dynamic Key type, N/A for OTP type, - optional for CA type - If set, host certificates that are requested are allowed to use - subdomains of those listed in "allowed_users". Defaults - to false. -
    • -
-
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/ssh/keys/my-key +``` -
Returns
-
- A `204` response code. -
+## Create Role -#### GET +This endpoint creates or updates a named role. -
-
Description
-
- Queries a named role. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/roles/:name` | `204 (empty body)` | -
Method
-
GET
+### Parameters -
URL
-
`/ssh/roles/`
+- `name` `(string: )` – Specifies the name of the role to create. This + is part of the request URL. -
Parameters
-
None
+- `key` `(string: "")` – Specifies the name of the registered key in Vault. + Before creating the role, use the `keys/` endpoint to create a named key. This + is required for "Dynamic Key" type. -
Returns
-
Note: these are examples only. For a dynamic key role: +- `admin_user` `(string: "")` – Specifies the admin user at remote host. The + shared key being registered should be for this user and should have root or + sudo privileges. Every time a dynamic credential is generated for a client, + Vault uses this admin username to login to remote host and install the + generated credential. This is required for Dynamic Key type. + +- `default_user` `(string: "")` – Specifies the default username for which a + credential will be generated. When the endpoint `creds/` is used without a + username, this value will be used as default username. Its recommended to + create individual roles for each username to ensure absolute isolation between + usernames. This is required for Dynamic Key type and OTP type. + + For the CA type, if you wish this to be a valid principal, it must also be + in `allowed_users`. + +- `cidr_list` `(string: "")` – Specifies a comma separated list of CIDR blocks + for which the role is applicable for.CIDR blocks can belong to more than one + role. + +- `exclude_cidr_list` `(string: "")` – Specifies a comma-separated list of CIDR + blocks. IP addresses belonging to these blocks are not accepted by the role. + This is particularly useful when big CIDR blocks are being used by the role + and certain parts need to be kept out. + +- `port` `(int: 22)` – Specifies the port number for SSH connection. Port number + does not play any role in OTP generation. For the `otp` backend type, this is + just a way to inform the client about the port number to use. The port number + will be returned to the client by Vault along with the OTP. + +- `key_type` `(string: )` – Specifies the type of credentials + generated by this role. This can be either `otp`, `dynamic` or `ca`. + +- `key_bits` `(int: 1024)` – Specifies the length of the RSA dynamic key in + bits. This can be either 1024 or 2048. + +- `install_script` + optional for Dynamic Key type, N/A for OTP type, + N/A for CA type + (String) + Script used to install and uninstall public keys in the target + machine. Defaults to the built-in script. + +- `allowed_users` `(string: "")` – If this option is not specified, client can + request for a credential for any valid user at the remote host, including the + admin user. If only certain usernames are to be allowed, then this list + enforces it. If this field is set, then credentials can only be created for + `default_user` and usernames present in this list. Setting this option will + enable all the users with access this role to fetch credentials for all other + usernames in this list. Use with caution. + +- `allowed_domains` `(string: "")` – If this option is not specified, client can + request for a signed certificate for any valid host. If only certain domains + are allowed, then this list enforces it. If this option is explicitly set to + `"*"`, then credentials can be created for any domain. + +- `key_option_specs` `(string: "")` – Specifies a aomma separated option + specification which will be prefixed to RSA keys in the remote host's + authorized_keys file. N.B.: Vault does not check this string for validity. + +- `ttl` `(string: "")` – Specifies the Time To Live value provided as a string + duration with time suffix. Hour is the largest suffix. If not set, uses the + system default value or the value of `max_ttl`, whichever is shorter. + +- `max_ttl` `(string: "")` – Specifies the maximum Time To Live provided as a + string duration with time suffix. Hour is the largest suffix. If not set, + defaults to the system maximum lease TTL. + +- `allowed_critical_options` `(string: "")` – Specifies a comma-separated list + of critical options that certificates can have when signed. To allow any + critical options, set this to an empty string. Will default to allowing any + critical options. + +- `allowed_extensions` `(string: "")` – Specifies a comma-separated list of + extensions that certificates can have when signed. To allow any critical + options, set this to an empty string. Will default to allowing any extensions. + +- `default_critical_options` `(map: "")` – Specifies a map of + critical options certificates should have if none are provided when signing. + This field takes in key value pairs in JSON format. Note that these are not + restricted by `allowed_critical_options`. Defaults to none. + +- `default_extensions` `(map: "")` – Specifies a map of + extensions certificates should have if none are provided when signing. This + field takes in key value pairs in JSON format. Note that these are not + restricted by `allowed_extensions`. Defaults to none. + +- `allow_user_certificates` `(bool: false)` – Specifies if certificates are + allowed to be signed for use as a 'user'. + +- `allow_host_certificates` `(bool: false)` – Specifies if certificates are + allowed to be signed for use as a 'host'. + +- `allow_bare_domains` `(bool: false)` – Specifies if host certificates that are + requested are allowed to use the base domains listed in "allowed_users", e.g. + "example.com". This is a separate option as in some cases this can be + considered a security threat. + +- `allow_subdomains` `(bool: false)` – Specifies if host certificates that are + requested are allowed to use subdomains of those listed in "allowed_users". + +### Sample Payload + +```json +{ + "key_type": "otp" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/roles/my-role +``` + +## Read Role + +This endpoint queries a named role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/ssh/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/ssh/roles/my-role +``` + +### Sample Response + +For a dynamic key role: ```json { @@ -322,9 +244,7 @@ update your API calls accordingly. } ``` -
- -
For an OTP role: +For an OTP role: ```json { @@ -334,8 +254,8 @@ update your API calls accordingly. "port": 22 } ``` -
-
For a CA role: + +For a CA role: ```json { @@ -351,89 +271,79 @@ update your API calls accordingly. "ttl": "4h" } ``` -
-#### LIST +## List Roles -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
+This endpoint returns a list of available roles. Only the role names are +returned, not any values. -
Method
-
LIST/GET
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/ssh/roles` | `200 application/json` | -
URL
-
`/ssh/roles` (LIST) or `/ssh/roles?list=true` (GET)
+### Sample Request -
Parameters
-
- None -
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/ssh/roles +``` -
Returns
-
+### Sample Response - ```json - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false - } - ``` +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` -
-
+## Delete Role -#### DELETE +This endpoint deletes a named role. -
-
Description
-
- Deletes a named role. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/ssh/roles/:name` | `204 (empty body)` | -
Method
-
DELETE
+### Parameters -
URL
-
`/ssh/roles/`
+- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. -
Parameters
-
None
+### Sample Request -
Returns
-
- A `204` response code. -
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + --data @payload.json \ + https://vault.rocks/v1/ssh/roles/my-role +``` -### /ssh/config/zeroaddress +## List Zero-Address Roles -#### GET +This endpoint returns the list of configured zero-address roles. -
-
Description
-
- Returns the list of configured zero-address roles. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/ssh/config/zeroaddress` | `200 application/json` | -
Method
-
GET
+### Sample Request -
URL
-
`/ssh/config/zeroaddress`
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/ssh/config/zeroaddress +``` -
Parameters
-
None
- -
Returns
-
+### Sample Response ```json { @@ -450,98 +360,94 @@ update your API calls accordingly. } ``` -
+## Configure Zero-Address Roles -#### POST +This endpoint configures zero-address roles. -
-
Description
-
- Configures zero-address roles. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/config/zeroaddress` | `204 (empty body)` | -
Method
-
POST
+### Parameters -
URL
-
`/ssh/config/zeroaddress`
+- `roles` `(string: )` – Specifies a string containing comma separated + list of role names which allows credentials to be requested for any IP + address. CIDR blocks previously registered under these roles will be ignored. -
Parameters
-
-
    -
  • - roles - required - A string containing comma separated list of role names which allows credentials to be requested - for any IP address. CIDR blocks previously registered under these roles will be ignored. -
    • -
-
+### Sample Payload -
Returns
-
- A `204` response code. -
+```json +{ + "roles": ["otp_key_role"] +} +``` -#### DELETE +### Sample Request -
-
Description
-
- Deletes the zero-address roles configuration. -
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/config/zeroaddress +``` -
Method
-
DELETE
+## Delete Zero-Address Role -
URL
-
`/ssh/config/zeroaddress`
+This endpoint deletes the zero-address roles configuration. -
Parameters
-
None
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/ssh/config/zeroaddress` | `204 (empty body)` | -
Returns
-
- A `204` response code. -
+### Sample Request +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/ssh/config/zeroaddress +``` -### /ssh/creds/ -#### POST +## Generate SSH Credentials -
-
Description
-
- Creates credentials for a specific username and IP with the - parameters defined in the given role. -
+This endpoint creates credentials for a specific username and IP with the +parameters defined in the given role. -
Method
-
POST
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/creds/:name` | `200 application/json` | -
URL
-
`/ssh/creds/`
+### Parameters -
Parameters
-
-
    -
  • - username - optional - (String) - Username on the remote host. -
    • -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
+- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is part of the request URL. -
Returns
-
For a dynamic key role: +- `username` `(string: "")` – Specifies the username on the remote host. + +- `ip` `(string: )` – Specifies the IP of the remote host. + +### Sample Payload + +```json +{ + "ip": "1.2.3.4" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/creds/my-role +``` + +### Sample Response + +For a dynamic key role: ```json { @@ -549,26 +455,24 @@ update your API calls accordingly. "renewable": false, "lease_duration": 0, "data": { - "admin_user": "rajanadar", - "allowed_users": "", - "cidr_list": "x.x.x.x/y", - "default_user": "rajanadar", - "exclude_cidr_list": "x.x.x.x/y", - "install_script": "pretty_large_script", - "key": "5d9ee6a1-c787-47a9-9738-da243f4f69bf", - "key_bits": 1024, - "key_option_specs": "", - "key_type": "dynamic", - "port": 22 - }, + "admin_user": "rajanadar", + "allowed_users": "", + "cidr_list": "x.x.x.x/y", + "default_user": "rajanadar", + "exclude_cidr_list": "x.x.x.x/y", + "install_script": "pretty_large_script", + "key": "5d9ee6a1-c787-47a9-9738-da243f4f69bf", + "key_bits": 1024, + "key_option_specs": "", + "key_type": "dynamic", + "port": 22 + }, "warnings": null, "auth": null } ``` -
- -
For an OTP role: +For an OTP role: ```json { @@ -576,48 +480,50 @@ update your API calls accordingly. "renewable": false, "lease_duration": 2764800, "data": { - "ip": "127.0.0.1", - "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2", - "key_type": "otp", - "port": 22, - "username": "rajanadar" - }, + "ip": "127.0.0.1", + "key": "6d6411fd-f622-ea0a-7e2c-989a745cbbb2", + "key_type": "otp", + "port": 22, + "username": "rajanadar" + }, "warnings": null, "auth": null } ``` -
+## List Roles by IP -### /ssh/lookup -#### POST +This endpoint lists all of the roles with which the given IP is associated. -
-
Description
-
- Lists all of the roles with which the given IP is associated. -
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/lookup` | `200 application/json` | -
Method
-
POST
+### Parameters -
URL
-
`/ssh/lookup`
+- `ip` `(string: )` – Specifies the IP of the remote host. -
Parameters
-
-
    -
  • - ip - required - (String) - IP of the remote host. -
    • -
-
+### Sample Payload -
Returns
-
An array of roles as a secret structure. +```json +{ + "ip": "1.2.3.4" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/lookup +``` + +### Sample Response + +An array of roles as a secret structure. ```json { @@ -625,237 +531,217 @@ update your API calls accordingly. "renewable": false, "lease_duration": 0, "data": { - "roles": ["fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", "6d6411fd-f622-ea0a-7e2c-989a745cbbb2"] - }, + "roles": [ + "fe6f61b7-7e4a-46a6-b2c8-0d530b8513df", + "6d6411fd-f622-ea0a-7e2c-989a745cbbb2" + ] + }, "warnings": null, "auth": null } ``` -
-### /ssh/verify -#### POST +## Verify SSH OTP -
-
Description
-
- Verifies if the given OTP is valid. This is an unauthenticated - endpoint. -
+This endpoint verifies if the given OTP is valid. This is an unauthenticated +endpoint. -
Method
-
POST
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/verify` | `200 application/json` | -
URL
-
`/ssh/verify`
+## Parameters -
Parameters
-
-
    -
  • - otp - required - (String) - One-Time-Key that needs to be validated. -
    • -
-
+- `otp` `(string: )` – Specifies the One-Time-Key that needs to be + validated. -
Returns
-
A `200` response code for a valid OTP. +### Sample Payload + +```json +{ + "otp": "bad2b3-..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/verify + +### Sample Response ```json { "lease_id":"", "renewable":false, "lease_duration":0, - "data":{ - "ip":"127.0.0.1", - "username":"rajanadar" - }, + "data": { + "ip":"127.0.0.1", + "username":"rajanadar" + }, "warnings":null, "auth":null } ``` -
+## Submit CA Information -
A `400` BadRequest response code with 'OTP not found' message, for an invalid OTP.
+This endpoint allows submitting the CA information for the backend via an SSH +key pair. _If you have already set a certificate and key, they will be +overridden._ -### /ssh/config/ca -#### POST +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/config/ca` | `200/204 application/json` | -
-
Description
-
- Allows submitting the CA information for the backend via an SSH key pair. - _If you have already set a certificate and key, they will be overridden._

-
+### Parameters -
Method
-
POST
+- `private_key` `(string: "")` – Specifies the private key part the SSH CA key + pair; required if `generate_signing_key` is false. -
URL
-
`/ssh/config/ca`
+- `public_key` `(string: "")` – Specifies the public key part of the SSH CA key + pair; required if `generate_signing_key` is false. -
Parameters
-
-
    -
  • - private_key - optional - The private key part the SSH CA key pair; required if generate_signing_key is false. -
    • -
  • - public_key - optional - The public key part of the SSH CA key pair; required if generate_signing_key is false. -
    • -
  • - generate_signing_key - optional - Generate the signing key pair interally if true, otherwise use the private_key and public_key fields. - The generated public key will be returned so you can add it to your configuration. -
    • -
-
+- `generate_signing_key` `(bool: false)` – Specifies if Vault should generate + the signing key pair internally. The generated public key will be returned so + you can add it to your configuration. -
Returns
-
- A `204` response code. And if generate_signing_key was true: -
-
- ```json - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "public_key": "ssh-rsa AAAAHHNzaC1y...\n" - }, - "warnings": null - } - ``` -
-
+### Sample Payload -#### GET +```json +{ + "generate_signing_key": true +} +``` -
-
Description
-
- Reads the configured/generated public key. -
+### Sample Request -
Method
-
GET
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/config/ca +``` -
URL
-
`/ssh/config/ca`
+### Sample Response -
Parameters
-
None
+This will return a `204` response if `generate_signing_key` was unset or false. -
Returns
-
- ```json - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "public_key": "ssh-rsa AAAAHHNzaC1y...\n" - }, - "warnings": null - } - ``` -
-
+This will return a `200` response if `generate_signing_key` was true: -### /ssh/sign -#### POST +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "public_key": "ssh-rsa AAAAHHNzaC1y...\n" + }, + "warnings": null +} +``` -
-
Description
-
- Signs an SSH public key based on the supplied parameters, subject to the - restrictions contained in the role named in the endpoint. -
+## Read Public Key -
Method
-
POST
+This endpoint reads the configured/generated public key. -
URL
-
`/ssh/sign/`
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/ssh/config/ca` | `200 application/json` | -
Parameters
-
-
    -
  • - public_key - required - SSH public key that should be signed. -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the role's `max_ttl` - value. If not provided, the role's `ttl` value will be used. Note that - the role values default to system values if not explicitly set. -
    • -
  • - valid_principals - optional - Valid principals, either usernames or hostnames, that the certificate - should be signed for. Defaults to none. -
    • -
  • - cert_type - optional - Type of certificate to be created; either "user" or "host". Defaults to - "user". -
    • -
  • - key_id - optional - Key id that the created certificate should have. If not specified, - the display name of the token will be used. -
    • -
  • - critical_options - optional - A map of the critical options that the certificate should be signed for. - Defaults to none. -
    • -
  • - extensions - optional - A map of the extensions that the certificate should be signed for. - Defaults to none -
    • -
-
+### Sample Request -
Returns
-
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/ssh/config/ca +``` - ```json - { - "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993", - "renewable": false, - "lease_duration": 21600, - "data": { - "serial_number": "f65ed2fd21443d5c", - "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n" - }, - "auth": null - } - ``` +### Sample Response -
-
-======= -The SSH secret backend has a full HTTP API. Please see the -[SSH secret backend API](/docs/http/secret/ssh/index.html) for more -details. ->>>>>>> e54ffcd1... Break out API documentation for secret backends +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "public_key": "ssh-rsa AAAAHHNzaC1y...\n" + }, + "warnings": null +} +``` + +## Sigh SSH Key + +This endpoint signs an SSH public key based on the supplied parameters, subject +to the restrictions contained in the role named in the endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/ssh/sign/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to sign. This + is part of the request URL. + +- `public_key` `(string: )` – Specifies the SSH public key that should + be signed. + +- `ttl` `(string: "")` – Specifies the Requested Time To Live. Cannot be greater + than the role's `max_ttl` value. If not provided, the role's `ttl` value will + be used. Note that the role values default to system values if not explicitly + set. + +- `vauld_principals` `(string: "")` – Specifies valid principals, either + usernames or hostnames, that the certificate should be signed for. + +- `cert_type` `(string: "user")` – Specifies the type of certificate to be + created; either "user" or "host". + +- `key_id` `(string: "")` – Specifies the key id that the created certificate + should have. If not specified, the display name of the token will be used. + +- `critical_options` `(map: "")` – Specifies a map of the + critical options that the certificate should be signed for. Defaults to none. + +- `extension` `(map: "")` – Specifies a map of the extensions + that the certificate should be signed for. Defaults to none. + +### Sample Payload + +```json +{ + "public_key": "ssh-rsa ..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/ssh/sign/my-key +``` + +### Sample Response + +```json +{ + "lease_id": "ssh/sign/example/097bf207-96dd-0041-0e83-b23bd1923993", + "renewable": false, + "lease_duration": 21600, + "data": { + "serial_number": "f65ed2fd21443d5c", + "signed_key": "ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...\n" + }, + "auth": null +} +``` From 9934b66fe095d1a5544555feab2bbbcdbe496165 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 09:48:45 -0700 Subject: [PATCH 10/17] Add new SSH field --- website/source/docs/http/secret/ssh/index.html.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/source/docs/http/secret/ssh/index.html.md b/website/source/docs/http/secret/ssh/index.html.md index d7fe1dcbd..b3c1d77ea 100644 --- a/website/source/docs/http/secret/ssh/index.html.md +++ b/website/source/docs/http/secret/ssh/index.html.md @@ -190,6 +190,11 @@ This endpoint creates or updates a named role. - `allow_subdomains` `(bool: false)` – Specifies if host certificates that are requested are allowed to use subdomains of those listed in "allowed_users". +- `allow_user_key_ids` `(bool: false)` – Specifies if users can override the key + ID for a signed certificate with the "key_id" field. When false, the key ID + will always be the token display name. The key ID is logged by the SSH server + and can be useful for auditing. + ### Sample Payload ```json @@ -262,6 +267,7 @@ For a CA role: "allow_bare_domains": false, "allow_host_certificates": true, "allow_subdomains": false, + "allow_user_key_ids": false, "allow_user_certificates": true, "allowed_critical_options": "", "allowed_extensions": "", From faef58b355b4169be8f8d89ec28f3414bb364c33 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 11:25:37 -0700 Subject: [PATCH 11/17] Fix Cassandra text --- website/source/docs/http/secret/cassandra/index.html.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/website/source/docs/http/secret/cassandra/index.html.md b/website/source/docs/http/secret/cassandra/index.html.md index 9d6a79be7..64952c547 100644 --- a/website/source/docs/http/secret/cassandra/index.html.md +++ b/website/source/docs/http/secret/cassandra/index.html.md @@ -149,12 +149,6 @@ $ curl \ https://vault.rocks/v1/cassandra/roles/my-role ``` -
Returns
-
- A `204` response code. -
-
- ## Read Role This endpoint queries the role definition. From b340d9ff8cee4df6691a8b49040f6027e7149304 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 11:25:59 -0700 Subject: [PATCH 12/17] Fix formatting in SSH --- website/source/docs/http/secret/ssh/index.html.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/website/source/docs/http/secret/ssh/index.html.md b/website/source/docs/http/secret/ssh/index.html.md index b3c1d77ea..7b6ce964e 100644 --- a/website/source/docs/http/secret/ssh/index.html.md +++ b/website/source/docs/http/secret/ssh/index.html.md @@ -125,12 +125,8 @@ This endpoint creates or updates a named role. - `key_bits` `(int: 1024)` – Specifies the length of the RSA dynamic key in bits. This can be either 1024 or 2048. -- `install_script` - optional for Dynamic Key type, N/A for OTP type, - N/A for CA type - (String) - Script used to install and uninstall public keys in the target - machine. Defaults to the built-in script. +- `install_script` `(string: "")` – Specifies the script used to install and + uninstall public keys in the target machine. Defaults to the built-in script. - `allowed_users` `(string: "")` – If this option is not specified, client can request for a credential for any valid user at the remote host, including the From 037700b86ea7e6e018eddd35c8f15dd41b1aa132 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 11:26:09 -0700 Subject: [PATCH 13/17] Update PKI backend API docs --- .../source/docs/http/secret/pki/index.html.md | 2480 ++++++++--------- 1 file changed, 1118 insertions(+), 1362 deletions(-) diff --git a/website/source/docs/http/secret/pki/index.html.md b/website/source/docs/http/secret/pki/index.html.md index 642b4e805..481e5b72d 100644 --- a/website/source/docs/http/secret/pki/index.html.md +++ b/website/source/docs/http/secret/pki/index.html.md @@ -16,1436 +16,1192 @@ This documentation assumes the PKI backend is mounted at the `/pki` path in Vault. Since it is possible to mount secret backends at any location, please update your API calls accordingly. +## Read CA Certificate -### /pki/ca(/pem) -#### GET +This endpoint retrieves the CA certificate *in raw DER-encoded form*. This is a +bare endpoint that does not return a standard Vault data structure. If `/pem` is +added to the endpoint, the CA certificate is returned in PEM format. -
-
Description
-
- Retrieves the CA certificate *in raw DER-encoded form*. This is a bare - endpoint that does not return a standard Vault data structure. If `/pem` is - added to the endpoint, the CA certificate is returned in PEM format.
-
This is an unauthenticated endpoint. -
+This is an unauthenticated endpoint. -
Method
-
GET
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/ca(/pem)` | `200 application/binary` | -
URL
-
`/pki/ca(/pem)`
+### Sample Request -
Parameters
-
- None -
+``` +$ curl \ + https://vault.rocks/v1/pki/ca/pem +``` -
Returns
-
+### Sample Response - ``` - - ``` +``` + +``` -
-
+## Read CA Certificate Chain -### /pki/ca_chain -#### GET +This endpoint retrieves the CA certificate chain, including the CA _in PEM +format_. This is a bare endpoint that does not return a standard Vault data +structure. -
-
Description
-
- Retrieves the CA certificate chain, including the CA *in PEM format*. This - is a bare endpoint that does not return a standard Vault data structure. -

This is an unauthenticated endpoint. -
+This is an unauthenticated endpoint. -
Method
-
GET
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/ca_chain` | `200 application/binary` | -
URL
-
`/pki/ca_chain`
+### Sample Request -
Parameters
-
- None -
+``` +$ curl \ + https://vault.rocks/v1/pki/ca_chain +``` -
Returns
-
+### Sample Response - ``` - - ``` +``` + +``` -
-
+## Read Certificate -### /pki/cert/ -#### GET +This endpoint etrieves one of a selection of certificates. This endpoint returns the certificate in PEM formatting in the +`certificate` key of the JSON object. -
-
Description
-
- Retrieves one of a selection of certificates. Valid values: `ca` for the CA - certificate, `crl` for the current CRL, `ca_chain` for the CA trust chain - or a serial number in either hyphen-separated or colon-separated octal - format. This endpoint returns the certificate in PEM formatting in the - `certificate` key of the JSON object.

This is an unauthenticated endpoint. -
+This is an unauthenticated endpoint. -
Method
-
GET
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/cert/:serial` | `200 application/json` | -
URL
-
`/pki/cert/`
+### Parameters -
Parameters
-
- None -
+- `serial` `(string: )` – Specifies the serial of the key to read. + This is part of the request URL. Valid values: are: -
Returns
-
+ - `ca` for the CA certificate + - `crl` for the current CRL + - `ca_chain` for the CA trust chain or a serial number in either hyphen-separated or colon-separated octal format - ```javascript - { - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n..." - } - } - ... - ``` +### Sample Request -
-
+``` +$ curl \ + https://vault.rocks/v1/pki/cert/crl +``` -### /pki/certs/ -#### LIST - -
-
Description
-
- Returns a list of the current certificates by serial number only. -
- -
Method
-
LIST/GET
- -
URL
-
`/pki/certs` (LIST) or `/pki/certs?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id":"", - "renewable":false, - "lease_duration":0, - "data":{ - "keys":[ - "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1", - "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21" - ] - }, - "wrap_info":null, - "warnings":null, - "auth":null - } - ... - ``` - -
-
- -### /pki/config/ca -#### POST - -
-
Description
-
- Allows submitting the CA information for the backend via a PEM file - containing the CA certificate and its private key, concatenated. Not needed - if you are generating a self-signed root certificate, and not used if you - have a signed intermediate CA certificate with a generated key (use the - `/pki/intermediate/set-signed` endpoint for that). _If you have already set - a certificate and key, they will be overridden._

The information - can be provided from a file via a `curl` command similar to the - following:
- - ```text - $ curl \ - -H "X-Vault-Token:06b9d..." \ - -X POST \ - --data "@cabundle.json" \ - http://127.0.0.1:8200/v1/pki/config/ca - ``` - - Note that if you provide the data through the HTTP API it must be - JSON-formatted, with newlines replaced with `\n`, like so: - - ```javascript - { - "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" - } - ``` -
- -
Method
-
POST
- -
URL
-
`/pki/config/ca`
- -
Parameters
-
-
    -
  • - pem_bundle - required - The key and certificate concatenated in PEM format. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/config/crl -#### GET - -
-
Description
-
- Allows getting the duration for which the generated CRL should be marked - valid. -
- -
Method
-
GET
- -
URL
-
`/pki/config/crl`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "expiry": "72h" - }, - "auth": null - } - ``` - -
-
- -#### POST - -
-
Description
-
- Allows setting the duration for which the generated CRL should be marked - valid. -
- -
Method
-
POST
- -
URL
-
`/pki/config/crl`
- -
Parameters
-
-
    -
  • -
  • - expiry - required - The time until expiration. Defaults to `72h`. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/config/urls - -#### GET - -
-
Description
-
- Fetch the URLs to be encoded in generated certificates. -
- -
Method
-
GET
- -
URL
-
`/pki/config/urls`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "issuing_certificates": [, ], - "crl_distribution_points": [, ], - "ocsp_servers": [, ], - }, - "auth": null - } - ``` - -
-
- -#### POST - -
-
Description
-
- Allows setting the issuing certificate endpoints, CRL distribution points, - and OCSP server endpoints that will be encoded into issued certificates. - You can update any of the values at any time without affecting the other - existing values. To remove the values, simply use a blank string as the - parameter. -
- -
Method
-
POST
- -
URL
-
`/pki/config/urls`
- -
Parameters
-
-
    -
  • - issuing_certificates - optional - The URL values for the Issuing Certificate field. -
    • -
  • - crl_distribution_points - optional - The URL values for the CRL Distribution Points field. -
    • -
  • - ocsp_servers - optional - The URL values for the OCSP Servers field. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/crl(/pem) -#### GET - -
-
Description
-
- Retrieves the current CRL *in raw DER-encoded form*. This endpoint - is suitable for usage in the CRL Distribution Points extension in a - CA certificate. This is a bare endpoint that does not return a - standard Vault data structure. If `/pem` is added to the endpoint, - the CRL is returned in PEM format. -

This is an unauthenticated endpoint. -
- -
Method
-
GET
- -
URL
-
`/pki/crl(/pem)`
- -
Parameters
-
- None -
- -
Returns
-
- - ``` - - ``` - -
-
- -### /pki/crl/rotate -#### GET - -
-
Description
-
- This endpoint forces a rotation of the CRL. This can be used - by administrators to cut the size of the CRL if it contains - a number of certificates that have now expired, but has - not been rotated due to no further certificates being revoked. -
- -
Method
-
GET
- -
URL
-
`/pki/crl/rotate`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "success": true - } - } - ``` - -
-
- -### /pki/intermediate/generate -#### POST - -
-
Description
-
- Generates a new private key and a CSR for signing. If using Vault as a - root, and for many other CAs, the various parameters on the final - certificate are set at signing time and may or may not honor the parameters - set here. _This will overwrite any previously existing CA private key._ If - the path ends with `exported`, the private key will be returned in the - response; if it is `internal` the private key will not be returned and - *cannot be retrieved later*.

This is mostly meant as a helper - function, and not all possible parameters that can be set in a CSR are - supported. -
- -
Method
-
POST
- -
URL
-
`/pki/intermediate/generate/[exported|internal]`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `csr` field will contain the private key (if - exported) and CSR, concatenated. -
    • -
  • - key_type - optional - Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use. Defaults to `2048`. Must be changed to a - valid value if the `key_type` is `ec`. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 21600, - "data": { - "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n", - "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----", - "private_key_type": "rsa" - }, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /pki/intermediate/set-signed -#### POST - -
-
Description
-
- Allows submitting the signed CA certificate corresponding to a private key generated via `/pki/intermediate/generate`. The certificate should be submitted in PEM format; see the documentation for `/pki/config/ca` for some hints on submitting. -
- -
Method
-
POST
- -
URL
-
`/pki/intermediate/set-signed`
- -
Parameters
-
-
    -
  • - certificate - required - The certificate in PEM format. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /pki/issue/ -#### POST - -
-
Description
-
- Generates a new set of credentials (private key and certificate) based on - the role named in the endpoint. The issuing CA certificate is returned as - well, so that only the root CA need be in a client's trust store.

*The private key is _not_ stored. If you do not save the private - key, you will need to request a new certificate.* -
- -
Method
-
POST
- -
URL
-
`/pki/issue/`
- -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. If the CN is allowed by role - policy, it will be issued. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. If any requested names do not match role policy, the - entire request will be denied. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. Only - valid if the role allows IP SANs (which is the default). -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the role's `max_ttl` - value. If not provided, the role's `ttl` value will be used. Note that - the role values default to system values if not explicitly set. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the private key and - certificate, concatenated; if the issuing CA is not a Vault-derived - self-signed root, this will be included as well. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n", - "private_key_type": "rsa", - "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "warnings": "", - "auth": null - } - ``` - -
-
- -### /pki/revoke -#### POST - -
-
Description
-
- Revokes a certificate using its serial number. This is an - alternative option to the standard method of revoking - using Vault lease IDs. A successful revocation will - rotate the CRL. -
- -
Method
-
POST
- -
URL
-
`/pki/revoke`
- -
Parameters
-
-
    -
  • - serial_number - required - The serial number of the certificate to revoke, in - hyphen-separated or colon-separated octal. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "revocation_time": 1433269787 - } - } - ``` -
-
- -### /pki/roles/ -#### POST - -
-
Description
-
- Creates or updates the role definition. Note that the - `allowed_domains`, `allow_subdomains`, and - `allow_any_name` attributes are additive; between them nearly and across - multiple roles nearly any issuing policy can be accommodated. - `server_flag`, `client_flag`, and `code_signing_flag` are additive as well. - If a client requests a certificate that is not allowed by the CN policy in - the role, the request is denied. -
- -
Method
-
POST
- -
URL
-
`/pki/roles/`
- -
Parameters
-
-
    -
  • - ttl - optional - The Time To Live value provided as a string duration with time suffix. - Hour is the largest suffix. If not set, uses the system default value - or the value of `max_ttl`, whichever is shorter. -
    • -
  • - max_ttl - optional - The maximum Time To Live provided as a string duration with time - suffix. Hour is the largest suffix. If not set, defaults to the system - maximum lease TTL. -
    • -
  • - allow_localhost - optional - If set, clients can request certificates for `localhost` as one of the - requested common names. This is useful for testing and to allow clients - on a single host to talk securely. Defaults to true. -
    • -
  • - allowed_domains - optional - Designates the domains of the role, provided as a comma-separated list. - This is used with the `allow_bare_domains` and `allow_subdomains` - options. There is no default. -
    • -
  • - allow_bare_domains - optional - If set, clients can request certificates matching the value of the - actual domains themselves; e.g. if a configured domain set with - `allowed_domains` is `example.com`, this allows clients to actually - request a certificate containing the name `example.com` as one of the - DNS values on the final certificate. In some scenarios, this can be - considered a security risk. Defaults to false. -
    • -
  • - allow_subdomains - optional - If set, clients can request certificates with CNs that are subdomains - of the CNs allowed by the other role options. _This includes wildcard - subdomains._ For example, an `allowed_domains` value of - `example.com` with this option set to true will allow `foo.example.com` - and `bar.example.com` as well as `*.example.com`. This is redundant - when using the `allow_any_name` option. Defaults to `false`. -
    • -
  • - allow_any_name - optional - If set, clients can request any CN. Useful in some circumstances, but - make sure you understand whether it is appropriate for your - installation before enabling it. Defaults to `false`. -
    • -
  • - enforce_hostnames - optional - If set, only valid host names are allowed for CNs, DNS SANs, and the - host part of email addresses. Defaults to `true`. -
    • -
  • - allow_ip_sans - optional - If set, clients can request IP Subject Alternative Names. No - authorization checking is performed except to verify that the given - values are valid IP addresses. Defaults to `true`. -
  • - server_flag - optional - If set, certificates are flagged for server use. Defaults to `true`. -
    • -
  • - client_flag - optional - If set, certificates are flagged for client use. Defaults to `true`. -
    • -
  • - code_signing_flag - optional - If set, certificates are flagged for code signing use. Defaults to - `false`. -
    • -
  • - email_protection_flag - optional - If set, certificates are flagged for email protection use. Defaults to - `false`. -
    • -
  • - key_type - optional - The type of key to generate for generated private - keys. Currently, `rsa` and `ec` are supported. - Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use for the generated keys. - Defaults to `2048`; this will need to be changed for - `ec` keys. See https://golang.org/pkg/crypto/elliptic/#Curve - for an overview of allowed bit lengths for `ec`. -
    • -
  • - key_usage - optional - This sets the allowed key usage constraint on issued certificates. This - is a comma-separated string; valid values can be found at - https://golang.org/pkg/crypto/x509/#KeyUsage -- simply drop the - `KeyUsage` part of the value. Values are not case-sensitive. To specify - no key usage constraints, set this to an empty string. Defaults to - `DigitalSignature,KeyAgreement,KeyEncipherment`. -
    • -
  • - use_csr_common_name - optional - If set, when used with the CSR signing endpoint, the common name in the - CSR will be used instead of taken from the JSON data. This does `not` - include any requested SANs in the CSR; use `use_csr_sans` for that. - Defaults to `true`. -
    • -
  • - use_csr_sans - optional - If set, when used with the CSR signing endpoint, the subject alternate - names in the CSR will be used instead of taken from the JSON data. This - does `not` include the common name in the CSR; use - `use_csr_common_name` for that. Defaults to `true`. -
    • -
  • - allow_token_displayname - optional - If set, the display name of the token used when requesting a - certificate will be considered to be a valid host name by the role. - Normal verification behavior applies with respect to subdomains and - wildcards. -
    • -
  • - ou - optional - This sets the OU (OrganizationalUnit) values in the subject field of - issued certificates. This is a comma-separated string. -
    • -
  • - organization - optional - This sets the O (Organization) values in the subject field of issued - certificates. This is a comma-separated string. -
    • -
  • - generate_lease - optional - If set, certificates issued/signed against this role will have Vault - leases attached to them. Defaults to "false". Certificates can be added - to the CRL by `vault revoke ` when certificates are - associated with leases. It can also be done using the `pki/revoke` - endpoint. However, when lease generation is disabled, invoking - `pki/revoke` would be the only way to add the certificates to the CRL. - When large number of certificates are generated with long lifetimes, it - is recommended that lease generation be disabled, as large amount of - leases adversely affect the startup time of Vault. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Queries the role definition. -
- -
Method
-
GET
- -
URL
-
`/pki/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "allow_any_name": false, - "allow_ip_sans": true, - "allow_localhost": true, - "allow_subdomains": false, - "allowed_domains": "example.com,foobar.com", - "client_flag": true, - "code_signing_flag": false, - "key_bits": 2048, - "key_type": "rsa", - "ttl": "6h", - "max_ttl": "12h", - "server_flag": true - } - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Returns a list of available roles. Only the role names are returned, not - any values. -
- -
Method
-
LIST/GET
- -
URL
-
`/pki/roles` (LIST) or `/pki/roles?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "keys": ["dev", "prod"] - }, - "lease_duration": 2764800, - "lease_id": "", - "renewable": false +### Sample Response +```json +{ + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n..." } - ``` +} +``` -
-
-#### DELETE +## List Certificates -
-
Description
-
- Deletes the role definition. Deleting a role does not revoke - certificates previously issued under this role. -
+This endpoint returns a list of the current certificates by serial number only. -
Method
-
DELETE
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/pki/certs` | `200 application/json` | -
URL
-
`/pki/roles/`
-
Parameters
-
- None -
+### Sample Request -
Returns
-
- A `204` response code. -
-
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/pki/certs +``` -### /pki/root/generate -#### POST +### Sample Response -
-
Description
-
- Generates a new self-signed CA certificate and private key. _This will - overwrite any previously-existing private key and certificate._ If the path - ends with `exported`, the private key will be returned in the response; if - it is `internal` the private key will not be returned and *cannot be - retrieved later*. Distribution points use the values set via `config/urls`. -

As with other issued certificates, Vault will automatically - revoke the generated root at the end of its lease period; the CA - certificate will sign its own CRL. -
+```json +{ + "lease_id":"", + "renewable":false, + "lease_duration":0, + "data":{ + "keys":[ + "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1", + "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21" + ] + }, + "wrap_info":null, + "warnings":null, + "auth":null +} +``` -
Method
-
POST
+## Submit CA Information -
URL
-
`/pki/root/generate/[exported|internal]`
+This endpoint allows submitting the CA information for the backend via a PEM +file containing the CA certificate and its private key, concatenated. Not needed +if you are generating a self-signed root certificate, and not used if you have a +signed intermediate CA certificate with a generated key (use the +`/pki/intermediate/set-signed` endpoint for that). _If you have already set a +certificate and key, they will be overridden._ -
Parameters
-
-
    -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - ttl - optional - Requested Time To Live (after which the certificate will be expired). - This cannot be larger than the mount max (or, if not set, the system - max). -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the private key (if - exported) and certificate, concatenated; if the issuing CA is not a - Vault-derived self-signed root, this will be included as well. -
    • -
  • - key_type - optional - Desired key type; must be `rsa` or `ec`. Defaults to `rsa`. -
    • -
  • - key_bits - optional - The number of bits to use. Defaults to `2048`. Must be changed to a - valid value if the `key_type` is `ec`. -
    • -
  • - max_path_length - optional - If set, the maximum path length to encode in the generated certificate. - Defaults to `-1`, which means no limit. unless the signing certificate - has a maximum path length set, in which case the path length is set to - one less than that of the signing certificate. A limit of `0` means a - literal path length of zero. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/config/ca` | `204 (empty body)` | -
Returns
-
+### Parameters - ```javascript - { - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` +- `pem_bundle` `(string: )` – Specifies the key and certificate concatenated in PEM format. -
-
+### Sample Request -### /pki/root/sign-intermediate -#### POST +```text +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data "@payload.json" \ + http://127.0.0.1:8200/v1/pki/config/ca +``` -
-
Description
-
- Uses the configured CA certificate to issue a certificate with appropriate - values for acting as an intermediate CA. Distribution points use the values - set via `config/urls`. Values set in the CSR are ignored unless - `use_csr_values` is set to true, in which case the values from the CSR are - used verbatim. -
+Note that if you provide the data through the HTTP API it must be +JSON-formatted, with newlines replaced with `\n`, like so: -
Method
-
POST
+```json +{ + "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" +} +``` -
URL
-
`/pki/root/sign-intermediate`
+## Read CRL Configuration -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - common_name - required - The requested CN for the certificate. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. -
    • -
  • - ttl - optional - Requested Time To Live (after which the certificate will be expired). - This cannot be larger than the mount max (or, if not set, the system - max). -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
  • - max_path_length - optional - If set, the maximum path length to encode in the generated certificate. - Defaults to `-1`, which means no limit. unless the signing certificate - has a maximum path length set, in which case the path length is set to - one less than that of the signing certificate. A limit of `0` means a - literal path length of zero. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
  • - use_csr_values - optional - If set to `true`, then: 1) Subject information, including names and - alternate names, will be preserved from the CSR rather than using the - values provided in the other parameters to this path; 2) Any key usages - (for instance, non-repudiation) requested in the CSR will be added to - the basic set of key usages used for CA certs signed by this path; 3) - Extensions requested in the CSR will be copied into the issued - certificate. -
    • -
-
+This endpoint allows getting the duration for which the generated CRL should be +marked valid. -
Returns
-
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/config/crl` | `200 application/json` | - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` +### Sample Request -
-
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/pki/config/crl +``` -### /pki/sign/ -#### POST +### Sample Response -
-
Description
-
- Signs a new certificate based upon the provided CSR and the supplied - parameters, subject to the restrictions contained in the role named in the - endpoint. The issuing CA certificate is returned as well, so that only the - root CA need be in a client's trust store. -
+```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "expiry": "72h" + }, + "auth": null +} +``` -
Method
-
POST
+## Set CRL Configuration -
URL
-
`/pki/sign/`
+This endpoint allows setting the duration for which the generated CRL should be +marked valid. -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - common_name - required - The requested CN for the certificate. If the CN is allowed by role - policy, it will be issued. -
    • -
  • - alt_names - optional - Requested Subject Alternative Names, in a comma-delimited list. These - can be host names or email addresses; they will be parsed into their - respective fields. If any requested names do not match role policy, the - entire request will be denied. -
    • -
  • - ip_sans - optional - Requested IP Subject Alternative Names, in a comma-delimited list. Only - valid if the role allows IP SANs (which is the default). -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the role's `max_ttl` - value. If not provided, the role's `ttl` value will be used. Note that - the role values default to system values if not explicitly set. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
  • - exclude_cn_from_sans - optional - If set, the given `common_name` will not be included in DNS or Email - Subject Alternate Names (as appropriate). Useful if the CN is not a - hostname or email address, but is instead some human-readable - identifier. -
    • -
-
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/config/crl` | `204 (empty body)` | -
Returns
-
+### Parameters - ```javascript - { - "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` +- `expiry` `(string: "72h")` – Specifies the time until expiration. -
-
+### Sample Payload -### /pki/sign-verbatim -#### POST +```json +{ + "expiry": "48h" +} +``` -
-
Description
-
- Signs a new certificate based upon the provided CSR. Values are taken - verbatim from the CSR; the _only_ restriction is that this endpoint will - refuse to issue an intermediate CA certificate (see the - `/pki/root/sign-intermediate` endpoint for that functionality.) _This is a - potentially dangerous endpoint and only highly trusted users should - have access._ -
+### Sample Request -
Method
-
POST
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/config/crl +``` -
URL
-
`/pki/sign-verbatim`
+## Read URLs -
Parameters
-
-
    -
  • - csr - required - The PEM-encoded CSR. -
    • -
  • - ttl - optional - Requested Time To Live. Cannot be greater than the mount's `max_ttl` - value. If not provided, the mount's `ttl` value will be used, which - defaults to system values if not explicitly set. -
    • -
  • - format - optional - Format for returned data. Can be `pem`, `der`, or `pem_bundle`; - defaults to `pem`. If `der`, the output is base64 encoded. If - `pem_bundle`, the `certificate` field will contain the certificate and, - if the issuing CA is not a Vault-derived self-signed root, it will be - concatenated with the certificate. -
    • -
-
+This endpoint fetches the URLs to be encoded in generated certificates. -
Returns
-
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/config/urls` | `200 application/json` | - ```javascript - { - "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05", - "renewable": false, - "lease_duration": 21600, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", - "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", - "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"] - "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" - }, - "auth": null - } - ``` +### Sample Request -
-
+``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/pki/config/urls +``` -### /pki/tidy -#### POST +### Sample Response -
-
Description
-
- Allows tidying up the backend storage and/or CRL by removing certificates - that have expired and are past a certain buffer period beyond their - expiration time. -
+```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "issuing_certificates": ["", ""], + "crl_distribution_points": ["", ""], + "ocsp_servers": ["", ""], + }, + "auth": null +} +``` -
Method
-
POST
+## Set URLs -
URL
-
`/pki/tidy`
+This endpoint allows setting the issuing certificate endpoints, CRL distribution +points, and OCSP server endpoints that will be encoded into issued certificates. +You can update any of the values at any time without affecting the other +existing values. To remove the values, simply use a blank string as the +parameter. -
Parameters
-
-
    -
  • - tidy_cert_store - optional - Whether to tidy up the certificate store. Defaults to `false`. -
    • -
  • - tidy_revocation_list - optional - Whether to tidy up the revocation list (CRL). Defaults to `false`. -
    • -
  • - safety_buffer - optional - A duration (given as an integer number of seconds or a string; defaults - to `72h`) used as a safety buffer to ensure certificates are not - expunged prematurely; as an example, this can keep certificates from - being removed from the CRL that, due to clock skew, might still be - considered valid on other hosts. For a certificate to be expunged, the - time must be after the expiration time of the certificate (according to - the local clock) plus the duration of `safety_buffer`. -
    • -
-
+| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/config/urls` | `204 (empty body)` | -
Returns
-
- A `204` status code. -
-
+### Parameters + +- `issuing_certificates` `(array: nil)` – Specifies the URL values for + the Issuing Certificate field. + +- `crl_distribution_points` `(array: nil)` – Specifies the URL values + for the CRL Distribution Points field. + +- `ocsp_servers` `(array: nil)` – Specifies the URL values for the OCSP + Servers field. + +### Sample Payload + +```json +{ + "ocsp_servers": ["https://..."] +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/config/urls +``` + +## Read CRL + +This endpoint retrieves the current CRL **in raw DER-encoded form**. This +endpoint is suitable for usage in the CRL Distribution Points extension in a CA +certificate. This is a bare endpoint that does not return a standard Vault data +structure. If `/pem` is added to the endpoint, the CRL is returned in PEM +format. + +This is an unauthenticated endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/crl(/pem)` | `200 application/binary` | + +### Sample Request + +``` +$ curl \ + https://vault.rocks/v1/pki/crl/pem +``` + +### Sample Response + +``` + +``` + +## Rotate CRLs + +This endpoint this endpoint forces a rotation of the CRL. This can be used by +administrators to cut the size of the CRL if it contains a number of +certificates that have now expired, but has not been rotated due to no further +certificates being revoked. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/crl/rotate` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/pki/crl/rotate +``` + +### Sample Response + +```json +{ + "data": { + "success": true + } +} +``` + +## Generate Intermediate + +This endpoint generates a new private key and a CSR for signing. If using Vault +as a root, and for many other CAs, the various parameters on the final +certificate are set at signing time and may or may not honor the parameters set +here. _This will overwrite any previously existing CA private key._ + +This is mostly meant as a helper function, and not all possible parameters that +can be set in a CSR are supported. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/intermediate/generate/:type` | `200 application/json` | + +### Parameters + +- `type` `(string: )` – Specifies the type of the intermediate to + create. If `exported`, the private key will be returned in the response; if + `internal` the private key will not be returned and *cannot be retrieved + later*. This is part of the request URL. + +- `common_name` `(string: )` – Specifies the requested CN for the + certificate. + +- `alt_names` `(string: "")` – Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. + +- `ip_sans` `(string: "")` – Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. + +- `format` `(string: "")` – Specifies the format for returned data. This can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `csr` field will contain the private key + (if exported) and CSR, concatenated. + +- `key_type` `(string: "rsa")` – Specifies the desired key type; must be `rsa` + or `ec`. + +- `key_bits` `(int: 2048)` – Specifies the number of bits to use. This must be + changed to a valid value if the `key_type` is `ec`. + +- `exclude_cn_from_sans` `(bool: false)` – If true, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +### Sample Payload + +```json +{ + "common_name": "www.example.com" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/intermediate/generate/internal +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 21600, + "data": { + "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n", + "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----", + "private_key_type": "rsa" + }, + "warnings": null, + "auth": null +} +``` + +## Set Signed Intermediate + +This endpoint allows submitting the signed CA certificate corresponding to a +private key generated via `/pki/intermediate/generate`. The certificate should +be submitted in PEM format; see the documentation for `/pki/config/ca` for some +hints on submitting. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/intermediate/set-signed` | `204 (empty body)` | + +## Parameters + +- `certificate` `(string: )` – Specifies the certificate in PEM + format. + +### Sample Payload + +```json +{ + "certificate": "-----BEGIN CERTIFICATE..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/intermediate/set-signed +``` + +## Generate Certificate + +This endpoint generates a new set of credentials (private key and certificate) +based on the role named in the endpoint. The issuing CA certificate is returned +as well, so that only the root CA need be in a client's trust store. + +**The private key is _not_ stored. If you do not save the private key, you will +**need to request a new certificate.** + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/issue/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create the + certificate against. This is part of the request URL. + +- `common_name` `(string: )` – Specifies the requested CN for the + certificate. If the CN is allowed by role policy, it will be issued. + +- `alt_names` `(string: "")` – Specifies requested Subject Alternative Names, in + a comma-delimited list. These can be host names or email addresses; they will + be parsed into their respective fields. If any requested names do not match + role policy, the entire request will be denied. + +- `ip_sans` `(string: "")` – Specifies requested IP Subject Alternative Names, + in a comma-delimited list. Only valid if the role allows IP SANs (which is the + default). + +- `ttl` `(string: "")` – Specifies requested Time To Live. Cannot be greater + than the role's `max_ttl` value. If not provided, the role's `ttl` value will + be used. Note that the role values default to system values if not explicitly + set. + +- `format` `(string: "")` – Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `certificate` field will contain the + private key and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `exclude_cn_from_sans` `(bool: false)` – If true, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + + +### Sample Payload + +```json +{ + "common_name": "www.example.com" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/issue/my-role +``` + +### Sample Response + +```json +{ + "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n", + "private_key_type": "rsa", + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "warnings": "", + "auth": null +} +``` + +## Revoke Certificate + +This endpoint revokes a certificate using its serial number. This is an +alternative option to the standard method of revoking using Vault lease IDs. A +successful revocation will rotate the CRL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/revoke` | `200 application/json` | + +### Parameters + +- `serial_number` `(string: )` – Specifies the serial number of the + certificate to revoke, in hyphen-separated or colon-separated octal. + +### Sample Payload + +```json +{ + "serial_number": "39:dd:2e..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/revoke +``` + +### Sample Response + +```json +{ + "data": { + "revocation_time": 1433269787 + } +} +``` + +## Create/Update Role + +This endpoint ceates or updates the role definition. Note that the +`allowed_domains`, `allow_subdomains`, and `allow_any_name` attributes are +additive; between them nearly and across multiple roles nearly any issuing +policy can be accommodated. `server_flag`, `client_flag`, and +`code_signing_flag` are additive as well. If a client requests a certificate +that is not allowed by the CN policy in the role, the request is denied. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is part of the request URL. + +- `ttl` `(string: "")` – Specifies the Time To Live value provided as a string + duration with time suffix. Hour is the largest suffix. If not set, uses the + system default value or the value of `max_ttl`, whichever is shorter. + +- `max_ttl` `(string: "")` – Specifies the maximum Time To Live provided as a + string duration with time suffix. Hour is the largest suffix. If not set, + defaults to the system maximum lease TTL. + +- `allow_localhost` `(bool: true)` – Specifies if clients can request + certificates for `localhost` as one of the requested common names. This is + useful for testing and to allow clients on a single host to talk securely. + +- `allowed_domains` `(string: "")` – Specifies the domains of the role, provided + as a comma-separated list. This is used with the `allow_bare_domains` and + `allow_subdomains` options. + +- `allow_bare_domains` `(bool: false)` – Specifies if clients can request + certificates matching the value of the actual domains themselves; e.g. if a + configured domain set with `allowed_domains` is `example.com`, this allows + clients to actually request a certificate containing the name `example.com` as + one of the DNS values on the final certificate. In some scenarios, this can be + considered a security risk. + +- `allow_subdomains` `(bool: false)` – Specifies if clients can request + certificates with CNs that are subdomains of the CNs allowed by the other role + options. _This includes wildcard subdomains._ For example, an + `allowed_domains` value of `example.com` with this option set to true will + allow `foo.example.com` and `bar.example.com` as well as `*.example.com`. This + is redundant when using the `allow_any_name` option. + +- `allow_any_name` `(bool: false)` – Specifies if clients can request any CN. + Useful in some circumstances, but make sure you understand whether it is + appropriate for your installation before enabling it. + +- `enforce_hostnames` `(bool: true)` – Specifies if only valid host names are + allowed for CNs, DNS SANs, and the host part of email addresses. + +- `allow_ip_sans` `(bool: true)` – Specifies if clients can request IP Subject + Alternative Names. No authorization checking is performed except to verify + that the given values are valid IP addresses. + +- `server_flag` `(bool: true)` – Specifies if certificates are flagged for + server use. + +- `client_flag` `(bool: true)` – Specifies if certificates are flagged for + client use. + +- `code_signing_flag` `(bool: false)` – Specifies if certificates are flagged + for code signing use. + +- `email_protection_flag` `(bool: false)` – Specifies if certificates are + flagged for email protection use. + +- `key_type` `(string: "rsa")` – Specifies the type of key to generate for + generated private keys. Currently, `rsa` and `ec` are supported. + +- `key_bits` `(int: 2048)` – Specifies the number of bits to use for the + generated keys. This will need to be changed for `ec` keys. See + https://golang.org/pkg/crypto/elliptic/#Curve for an overview of allowed bit + lengths for `ec`. + +- `key_usage` `(string: "DigitalSignature,KeyAgreement,KeyEncipherment")` – + Specifies the allowed key usage constraint on issued certificates. This is a + comma-separated string; valid values can be found at + https://golang.org/pkg/crypto/x509/#KeyUsage - simply drop the `KeyUsage` part + of the value. Values are not case-sensitive. To specify no key usage + constraints, set this to an empty string. + +- `use_csr_common_name` `(bool: true)` – When used with the CSR signing + endpoint, the common name in the CSR will be used instead of taken from the + JSON data. This does `not` include any requested SANs in the CSR; use + `use_csr_sans` for that. + +- `use_csr_sans` `(bool: true)` – When used with the CSR signing endpoint, the + subject alternate names in the CSR will be used instead of taken from the JSON + data. This does `not` include the common name in the CSR; use + `use_csr_common_name` for that. + +- `allow_token_displayname` `(bool: false)` – If set, the display name of the + token used when requesting a certificate will be considered to be a valid host + name by the role. Normal verification behavior applies with respect to + subdomains and wildcards. + +- `ou` `(string: "")` – Specifies the OU (OrganizationalUnit) values in the + subject field of issued certificates. This is a comma-separated string. + +- `organization` `(string: "")` – Specifies the O (Organization) values in the + subject field of issued certificates. This is a comma-separated string. + +- `generate_lease` `(bool: false)` – Specifies if certificates issued/signed + against this role will have Vault leases attached to them. Certificates can be + added to the CRL by `vault revoke ` when certificates are associated + with leases. It can also be done using the `pki/revoke` endpoint. However, + when lease generation is disabled, invoking `pki/revoke` would be the only way + to add the certificates to the CRL. When large number of certificates are + generated with long lifetimes, it is recommended that lease generation be + disabled, as large amount of leases adversely affect the startup time of + Vault. + +### Sample Payload + +```json +{ + "allowed_domains": "example.com", + "allow_subdomains": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/roles/my-role +``` + +## Read Role + +This endpoint queries the role definition. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/pki/roles/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/pki/roles/my-role +``` + +### Sample Response + +```json +{ + "data": { + "allow_any_name": false, + "allow_ip_sans": true, + "allow_localhost": true, + "allow_subdomains": false, + "allowed_domains": "example.com,foobar.com", + "client_flag": true, + "code_signing_flag": false, + "key_bits": 2048, + "key_type": "rsa", + "ttl": "6h", + "max_ttl": "12h", + "server_flag": true + } +} +``` + +## List Roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/pki/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/pki/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete Role + +This endpoint deletes the role definition. Deleting a role **does not** +revoke certificates previously issued under this role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/pki/roles/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/pki/roles/my-role +``` + +## Generate Root + +This endpoint generates a new self-signed CA certificate and private key. _This +will overwrite any previously-existing private key and certificate._ If the path +ends with `exported`, the private key will be returned in the response; if it is +`internal` the private key will not be returned and *cannot be retrieved later*. +Distribution points use the values set via `config/urls`. + +As with other issued certificates, Vault will automatically revoke the generated +root at the end of its lease period; the CA certificate will sign its own CRL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/root/generate/:type` | `200 application/json` | + + +### Parameters + +- `type` `(string: )` – Specifies the type of the root to + create. If `exported`, the private key will be returned in the response; if + `internal` the private key will not be returned and *cannot be retrieved + later*. This is part of the request URL. + +- `common_name` `(string: )` – Specifies the requested CN for the + certificate. + +- `alt_names` `(string: "")` – Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. + +- `ip_sans` `(string: "")` – Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. + +- `ttl` `(string: "")` – Specifies the requested Time To Live (after which the + certificate will be expired). This cannot be larger than the mount max (or, if + not set, the system max). + +- `format` `(string: "pem")` – Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the private key (if + exported) and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `key_type` `(string: "rsa")` – Specifies the desired key type; must be `rsa` + or `ec`. + +- `key_bits` `(int: 2048)` – Specifies the number of bits to use. Must be + changed to a valid value if the `key_type` is `ec`. + +- `max_path_length` `(int: -1)` – Specifies the maximum path length to encode in + the generated certificate. `-1` means no limit. Unless the signing certificate + has a maximum path length set, in which case the path length is set to one + less than that of the signing certificate. A limit of `0` means a literal + path length of zero. + +- `exclude_cn_from_sans` `(bool: false)` – If set, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +### Sample Payload + +```json +{ + "common_name": "example.com" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/root/generate/internal +``` + +### Sample Response + +```json +{ + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +## Sign Intermediate + +This endpoint uses the configured CA certificate to issue a certificate with +appropriate values for acting as an intermediate CA. Distribution points use the +values set via `config/urls`. Values set in the CSR are ignored unless +`use_csr_values` is set to true, in which case the values from the CSR are used +verbatim. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/root/sign-intermediate` | `200 application/json` | + +### Parameters + +- `csr` `(string: )` – Specifies the PEM-encoded CSR. + +- `common_name` `(string: )` – Specifies the requested CN for the + certificate. + +- `alt_names` `(string: "")` – Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. + +- `ip_sans` `(string: "")` – Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. + +- `ttl` `(string: "")` – Specifies the requested Time To Live (after which the + certificate will be expired). This cannot be larger than the mount max (or, if + not set, the system max). + +- `format` `(string: "pem")` – Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, if the + issuing CA is not a Vault-derived self-signed root, it will be concatenated + with the certificate. + +- `max_path_length` `(int: -1)` – Specifies the maximum path length to encode in + the generated certificate. `-1`, means no limit, unless the signing + certificate has a maximum path length set, in which case the path length is + set to one less than that of the signing certificate. A limit of `0` means a + literal path length of zero. + +- `exclude_cn_from_sans` `(string: "")` – Specifies the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +- `use_csr_values` `(bool: false)` – If set to `true`, then: 1) Subject + information, including names and alternate names, will be preserved from the + CSR rather than using the values provided in the other parameters to this + path; 2) Any key usages (for instance, non-repudiation) requested in the CSR + will be added to the basic set of key usages used for CA certs signed by this + path; 3) Extensions requested in the CSR will be copied into the issued + certificate. + +### Sample Payload + +```json +{ + "csr": "...", + "common_name": "example.com" + +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/root/sign-intermediate +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +## Sign Certificate + +This endpoint signs a new certificate based upon the provided CSR and the +supplied parameters, subject to the restrictions contained in the role named in +the endpoint. The issuing CA certificate is returned as well, so that only the +root CA need be in a client's trust store. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/sign/:name` | `200 application/json` | + +### Parameters + +- `csr` `(string: )` – Specifies the PEM-encoded CSR. + +- `common_name` `(string: )` – Specifies the requested CN for the + certificate. If the CN is allowed by role policy, it will be issued. + +- `alt_names` `(string: "")` – Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. If any requested names do + not match role policy, the entire request will be denied. + +- `ip_sans` `(string: "")` – Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. Only valid if the role allows IP SANs (which + is the default). + +- `ttl` `(string: "")` – Specifies the requested Time To Live. Cannot be greater + than the role's `max_ttl` value. If not provided, the role's `ttl` value will + be used. Note that the role values default to system values if not explicitly + set. + +- `format` `(string: "pem")` – Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, if the + issuing CA is not a Vault-derived self-signed root, it will be concatenated + with the certificate. + +- `exclude_cn_from_sans` `(bool: false)` – If set, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +### Sample Payload + +```json +{ + "csr": "...", + "common_name": "example.com" +} +``` + +### Sample Response + +```json +{ + "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +## Sign Verbatim + +This endpoint signs a new certificate based upon the provided CSR. Values are +taken verbatim from the CSR; the _only_ restriction is that this endpoint will +refuse to issue an intermediate CA certificate (see the +`/pki/root/sign-intermediate` endpoint for that functionality.) + +**This is a potentially dangerous endpoint and only highly trusted users should +have access.** + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/sign-verbatim` | `200 application/json` | + +### Parameters + +- `csr` `(string: )` – Specifies the PEM-encoded CSR. + +- `ttl` `(string: "")` – Specifies the requested Time To Live. Cannot be greater + than the mount's `max_ttl` value. If not provided, the mount's `ttl` value + will be used, which defaults to system values if not explicitly set. + +- `format` `(string: "pem")` – Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, if the + issuing CA is not a Vault-derived self-signed root, it will be concatenated + with the certificate. + +### Sample Payload + +```json +{ + "csr": "..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/sign-verbatim +``` + +### Sample Response + +```json +{ + "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": ["-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n"], + "serial": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +## Tidy + +This endpoint allows tidying up the backend storage and/or CRL by removing +certificates that have expired and are past a certain buffer period beyond their +expiration time. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/pki/tidy` | `200 application/json` | + +### Parameters + +- `tidy_cert_store` `(bool: false)` Specifies whether to tidy up the certificate + store. + +- `tidy_revocation_list` `(bool: false)` Specifies whether to tidy up the + revocation list (CRL). + +- `safety_buffer` `(string: "")` Specifies A duration (given as an integer + number of seconds or a string; defaults to `72h`) used as a safety buffer to + ensure certificates are not expunged prematurely; as an example, this can keep + certificates from being removed from the CRL that, due to clock skew, might + still be considered valid on other hosts. For a certificate to be expunged, + the time must be after the expiration time of the certificate (according to + the local clock) plus the duration of `safety_buffer`. + +### Sample Payload + +```json +{ + "safety_buffer": "24h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/pki/tidy +``` From 5c1f017274eb7d2a23c481cd292bf7d0b188c5b8 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 11:57:06 -0700 Subject: [PATCH 14/17] Reformat replication API --- .../source/docs/guides/replication.html.md | 42 +- .../docs/http/sys-replication-primary.html.md | 206 --------- .../http/sys-replication-secondary.html.md | 197 --------- .../source/docs/http/sys-replication.html.md | 118 ----- .../docs/http/system/replication.html.md | 417 ++++++++++++++++++ .../replication/index.html.md | 11 +- website/source/layouts/http.erb | 3 + 7 files changed, 441 insertions(+), 553 deletions(-) delete mode 100644 website/source/docs/http/sys-replication-primary.html.md delete mode 100644 website/source/docs/http/sys-replication-secondary.html.md delete mode 100644 website/source/docs/http/sys-replication.html.md create mode 100644 website/source/docs/http/system/replication.html.md diff --git a/website/source/docs/guides/replication.html.md b/website/source/docs/guides/replication.html.md index 4fc7c5183..48305f26c 100644 --- a/website/source/docs/guides/replication.html.md +++ b/website/source/docs/guides/replication.html.md @@ -7,25 +7,19 @@ description: |- --- If you're unfamiliar with Vault Replication concepts, please first look at the -[general information -page](https://www.vaultproject.io/docs/vault-enterprise/replication/index.html). -More details can be found in the [replication -internals](https://www.vaultproject.io/docs/internals/replication.html) -document. +[general information page](/docs/vault-enterprise/replication/index.html). More +details can be found in the +[replication internals](/docs/internals/replication.html) document. -Also, note that full details of the API are available the endpoints relevant to -the -[primary](https://www.vaultproject.io/docs/http/sys-replication-primary.html) -cluster, the -[secondary](https://www.vaultproject.io/docs/http/sys-replication-secondary.html) -cluster, and endpoints [relevant to -both](https://www.vaultproject.io/docs/http/sys-replication.html). +Vault replication also includes a complete API. For more information, please see +the [Vault Replication API documentation](/docs/http/system/replication.html) -## Activating Replication + +## Activating Replication ### Activating the Primary -To activate the primary, run `vault write -f sys/replication/primary/enable`. +To activate the primary, run `vault write -f sys/replication/primary/enable`. There is currently one optional argument: `primary_cluster_addr`. This can be used to override the cluster address that the primary advertises to the @@ -35,17 +29,17 @@ members of a single cluster and primary/secondary clusters. ### Fetching a Secondary Token To fetch a secondary bootstrap token, run `vault write -sys/replication/primary/secondary-token id=`. +sys/replication/primary/secondary-token id=`. The value for ID is opaque to Vault and can be any identifying value you want; this can be used later to revoke the secondary and will be listed when you read replication status on the primary. You will get back a normal wrapped response, -except that the token will be a JWT instead of UUID-formatted random bytes. +except that the token will be a JWT instead of UUID-formatted random bytes. ### Activating a Secondary To activate a secondary, run `vault write sys/replication/secondary/enable -token=`. +token=`. You must provide the full token value. Be very careful when running this command, as it will destroy all data currently stored in the secondary. @@ -69,7 +63,7 @@ remove it from rotation (e.g. if using Consul for service discovery), but if a standby does not attempt taking over it will throw errors. We hope to make this workflow better in a future update. -### Dev-Mode Root Tokens +### Dev-Mode Root Tokens To ease development and testing, when both the primary and secondary are running in development mode, the initial root token created by the primary @@ -85,7 +79,7 @@ as policies and auth backend configuration are replicated. The generate-root command can be also be used to generate a root token local to the secondary cluster. -## Managing Vault Replication +## Managing Vault Replication Vault’s replication model is intended to allow horizontally scaling Vault’s functions rather than to act in a strict Disaster Recovery (DR) capacity. As a @@ -151,7 +145,7 @@ mounts would be unable to be read). In normal Vault usage, if Vault has at least one audit backend configured and is unable to successfully log to at least one backend, it will block further -requests. +requests. Replicated audit mounts must be able to successfully log on all replicated clusters. For example, if using the file backend, the configured path must be @@ -167,12 +161,10 @@ secondaries are ever reconnected. ### Disaster Recovery At the moment, because leases and tokens are not replicated, if you need true -DR, you will need a DR solution per cluster (similar to non-replicated Vault). +DR, you will need a DR solution per cluster (similar to non-replicated Vault). Local backend mounts are not replicated and their use will require existing DR -mechanisms if DR is necessary in your implementation. +mechanisms if DR is necessary in your implementation. We may pursue a dedicated Disaster Recovery-focused Replication Mode at a -future time. - - +future time. diff --git a/website/source/docs/http/sys-replication-primary.html.md b/website/source/docs/http/sys-replication-primary.html.md deleted file mode 100644 index 1d06b5a21..000000000 --- a/website/source/docs/http/sys-replication-primary.html.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/repliation/primary" -sidebar_current: "docs-http-replication-primary" -description: |- - The '/sys/replication/primary' endpoint focuses on managing replication behavior for a primary cluster, including management of secondaries. ---- - -# /sys/replication/primary/enable - -## POST - -
-
Description
-
- Enables replication in primary mode. This is used when replication is - currently disabled on the cluster (if the cluster is already a secondary, - it must be promoted). - - Caution: only one primary should be active at a given time. Multiple - primaries may result in data loss! - -
- -
Method
-
POST
- -
URL
-
`/sys/repliation/primary/enable`
- -
Parameters
-
-
    -
  • - primary_cluster_addr /span> - optional - Can be used to override the cluster address that the primary gives to - secondary nodes. Useful if the primary’s cluster address is not - directly accessible and must be accessed via an alternate path/address, - such as through a TCP-based load balancer. -
    • -
-
- -
Returns
-
- `200` response code with a warning. -
-
- -# /sys/replication/primary/demote - -## POST - -
-
Description
-
- Demotes a primary cluster to a secondary. This secondary cluster will not - attempt to connect to a primary (see the update-primary call), but will - maintain knowledge of its cluster ID and can be reconnected to the same - replication set without wiping local storage. -
- -
Method
-
POST
- -
URL
-
`/sys/repliation/primary/demote`
- -
Parameters
-
- None -
- -
Returns
-
- `200` response code with a warning. -
-
- - -# /sys/replication/primary/disable - -## POST - -
-
Description
-
- Disable replication entirely on the cluster. Any secondaries will no longer - be able to connect. Caution: re-enabling this node as a primary or secondary - will change its cluster ID; in the secondary case this means a wipe of the - underlying storage when connected to a primary, and in the primary case, - secondaries connecting back to the cluster (even if they have connected - before) will require a wipe of the underlying storage. -
- -
Method
-
POST
- -
URL
-
`/sys/repliation/primary/disable`
- -
Parameters
-
- None -
- -
Returns
-
- `200` response code with a warning.. -
-
- -# /sys/replication/primary/secondary-token - -## GET - -
-
Description
-
- Requires ‘sudo’ capability. Generate a secondary activation token for the - cluster with the given opaque identifier, which must be unique. This - identifier can later be used to revoke a secondary's access. -
- -
Method
-
GET
- -
URL
-
`/sys/replication/primary/secondary-token`
- -
Parameters
-
-
    -
  • - id - required - An opaque identifier, e.g. ‘us-east’ -
    • -
  • - ttl - optional - The TTL for the secondary activation token. Defaults to ‘"30m"’. -
    • -
-
- -
Returns
-
- - ```javascript - { - "request_id": "", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": null, - "warnings": null, - "wrap_info": { - "token": "fb79b9d3-d94e-9eb6-4919-c559311133d6", - "ttl": 300, - "creation_time": "2016-09-28T14:41:00.56961496-04:00", - "wrapped_accessor": "" - } - } - ``` - -
-
- -# /sys/replication/primary/revoke-secondary - -## POST - -
-
Description
-
- Revoke a secondary’s ability to connect to the primary cluster; the - secondary will immediately be disconnected and will not be allowed to - connect again unless given a new activation token. -
- -
Method
-
- -
URL
-
`/sys/replication/secondary/revoke-secondary`
- -
Parameters
-
-
    -
  • - id - required - The identifier used when fetching the secondary token. -
    • -
-
- -
Returns
-
- `200` response code with a warning. -
-
- - diff --git a/website/source/docs/http/sys-replication-secondary.html.md b/website/source/docs/http/sys-replication-secondary.html.md deleted file mode 100644 index f8db0b101..000000000 --- a/website/source/docs/http/sys-replication-secondary.html.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/replication/secondary" -sidebar_current: "docs-http-replication-secondary" -description: |- - The '/sys/replication/secondary' endpoint focuses on replication management operations on secondary clusters. ---- - -# /sys/replication/secondary/enable - -## POST - -
-
Description
-
- Enables replication on a secondary using a secondary activation token. - - Caution: this will immediately clear all data in the cluster! -
- -
Method
-
- -
URL
-
`/sys/replication/secondary/enable`
- -
Parameters
-
-
    -
  • - token - required - The secondary activation token fetched from the primary. -
    • -
  • - primary_api_addr - optional - Set this to the API address (normal Vault address) to override the - value embedded in the token. This can be useful if the primary’s - redirect address is not accessible directly from this cluster (e.g. - through a load balancer). -
    • -
  • - ca_file - optional - The path to a CA root file (PEM format) that the secondary can use when - unwrapping the token from the primary. If this and ca_path are not - given, defaults to system CA roots. -
    • -
  • - ca_path - optional - The path to a CA root directory containing PEM-format files that the - secondary can use when unwrapping the token from the primary. If this - and ca_file are not given, defaults to system CA roots. -
    • -
-
- -
Returns
-
- `200` response code and a warning. -
-
- - -# /sys/replication/secondary/promote - -## POST - -
-
Description
-
- Promotes the secondary cluster to primary. For data safety and security - reasons, new secondary tokens will need to be issued to other secondaries, - and there should never be more than one primary at a time. -
- -
Method
-
- -
URL
-
`/sys/replication/secondary/promote`
- -
Parameters
-
-
    -
  • - primary_cluster_addr - optional - Can be used to override the cluster address that the primary gives to - secondary nodes. Useful if the primary’s cluster address is not - directly accessible and must be accessed via an alternate path/address - (e.g. through a load balancer). -
    • -
-
- -
Returns
-
- `200` response code and a warning. -
-
- -# /sys/replication/secondary/disable - -## POST - -
-
Description
-
- Disable replication entirely on the cluster. The cluster will no longer be - able to connect to the primary. - - Caution: re-enabling this node as a primary or secondary will change its - cluster ID; in the secondary case this means a wipe of the underlying - storage when connected to a primary, and in the primary case, secondaries - connecting back to the cluster (even if they have connected before) will - require a wipe of the underlying storage. -
- -
Method
-
- -
URL
-
`/sys/replication/secondary/disable`
- -
Parameters
-
- None -
- -
Returns
-
- `200` response code and a warning. -
-
- -# /sys/replication/secondary/update-primary - -## POST - -
-
Description
-
- Change a secondary cluster’s assigned primary - cluster using a secondary activation token. - This does not wipe all data in the cluster. -
- -
Method
-
- -
URL
-
`/sys/replication/secondary/update-primary`
- -
Parameters
-
-
    -
  • - token - required - The secondary activation token fetched from the primary. If you set - this to a blank string, the cluster will stay a secondary but clear its - knowledge of any past primary (and thus not attempt to connect to the - previous primary). This can be useful if the primary is down to stop - the secondary from trying to reconnect to it. -
    • -
  • - primary_api_addr - optional - Set this to the API address (normal Vault address) to override the - value embedded in the token. This can be useful if the primary’s - redirect address is not accessible directly from this cluster. -
    • -
  • - ca_file - optional - The path to a CA root file (PEM format) that the secondary can use when - unwrapping the token from the primary. If this and ca_path are not - given, defaults to system CA roots. -
    • -
  • - ca_path - optional - The path to a CA root directory containing PEM-format files that the - secondary can use when unwrapping the token from the primary. If this - and ca_file are not given, defaults to system CA roots. -
    • -
-
- -
Returns
-
- `200` response code and a warning. -
-
diff --git a/website/source/docs/http/sys-replication.html.md b/website/source/docs/http/sys-replication.html.md deleted file mode 100644 index 8a57f2ee3..000000000 --- a/website/source/docs/http/sys-replication.html.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -layout: "http" -page_title: "HTTP API: /sys/replication" -sidebar_current: "docs-http-replication" -description: |- - The '/sys/replication' endpoint focuses on managing general operations in Vault Enterprise replication sets ---- - -# /sys/replication/recover - -## POST - -
-
Description
-
- Attempts recovery if replication is in an adverse state. For example: an - error has caused replication to stop syncing. -
- -
Method
-
POST
- -
URL
-
`/sys/replication/recover`
- -
Parameters
-
- None -
- -
Returns
-
- A `200` response code and a warning. -
-
- - -# /sys/replication/reindex - -## POST - -
-
Description
-
- Requires ‘sudo’ capability. Reindex the local data storage. This can cause - a very long delay depending on the number and size of objects in the data - store. -
- -
Method
-
POST
- -
URL
-
`/sys/replication/reindex`
- -
Parameters
-
- None -
- -
Returns
-
- A `200` response code and a warning. -
-
- -# /sys/replication/status - -## GET - -
-
Description
-
- Unauthenticated. Print information about the status of replication (mode, - sync progress, etc). -
- -
Method
-
GET
- -
URL
-
`/sys/replication/status`
- -
Parameters
-
- None -
- -
Returns
-
- The printed status of the replication environment. As an example, for a - primary, it will look something like: - - ```javascript - { - "mode": "primary", - "cluster_id": "d4095d41-3aee-8791-c421-9bc7f88f7c3e", - "known_secondaries": [], - "last_wal": 0, - "merkle_root": "c3260c4c682ff2d6eb3c8bfd877134b3cec022d1", - "request_id": "009ea98c-06cd-6dc3-74f2-c4904b22e535", - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "cluster_id": "d4095d41-3aee-8791-c421-9bc7f88f7c3e", - "known_secondaries": [], - "last_wal": 0, - "merkle_root": "c3260c4c682ff2d6eb3c8bfd877134b3cec022d1", - "mode": "primary" - }, - "wrap_info": null, - "warnings": null, - "auth": null - } - ``` -
-
diff --git a/website/source/docs/http/system/replication.html.md b/website/source/docs/http/system/replication.html.md new file mode 100644 index 000000000..869ac485d --- /dev/null +++ b/website/source/docs/http/system/replication.html.md @@ -0,0 +1,417 @@ +--- +layout: "http" +page_title: "/sys/replication - HTTP API" +sidebar_current: "docs-http-system-replication" +description: |- + The '/sys/replication' endpoint focuses on managing general operations in Vault Enterprise replication sets +--- + +# `/sys/replication` + +~> **Enterprise Only** – This endpoint requires Vault Pro or Vault Enterprise. + +## Attempt Recovery + +This endpoint attempts recovery if replication is in an adverse state. For +example: an error has caused replication to stop syncing. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/recover` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/sys/replication/recover +``` + +### Sample Response + +```json +{ + "warnings": ["..."] +} +``` + +## Reindex Replication + +This endpoint reindexes the local data storage. This can cause a very long delay +depending on the number and size of objects in the data store. + +**This endpoint requires 'sudo' capability.** + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/reindex` | `200 application/json` | + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/sys/replication/reindex +``` + +### Sample Response + +```json +{ + "warnings": ["..."] +} +``` + +## Check Status + +This endpoint print information about the status of replication (mode, +sync progress, etc). + +This is an authenticated endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/replication/status` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + https://vault.rocks/v1/sys/replication/status +``` + +### Sample Response + +The printed status of the replication environment. As an example, for a +primary, it will look something like: + +```json +{ + "mode": "primary", + "cluster_id": "d4095d41-3aee-8791-c421-9bc7f88f7c3e", + "known_secondaries": [], + "last_wal": 0, + "merkle_root": "c3260c4c682ff2d6eb3c8bfd877134b3cec022d1", + "request_id": "009ea98c-06cd-6dc3-74f2-c4904b22e535", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "cluster_id": "d4095d41-3aee-8791-c421-9bc7f88f7c3e", + "known_secondaries": [], + "last_wal": 0, + "merkle_root": "c3260c4c682ff2d6eb3c8bfd877134b3cec022d1", + "mode": "primary" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Enable Primary Replication + +This endpoint enables replication in primary mode. This is used when replication +is currently disabled on the cluster (if the cluster is already a secondary, it +must be promoted). + +!> Only one primary should be active at a given time. Multiple primaries may +result in data loss! + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/primary/enable` | `204 (empty body)` | + +### Parameters + +- `primary_cluster_addr` `(string: "")` – Specifies the cluster address that the + primary gives to secondary nodes. Useful if the primary's cluster address is + not directly accessible and must be accessed via an alternate path/address, + such as through a TCP-based load balancer. + +### Sample Payload + +```json +{} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/replication/primary/enable +``` + +## Demote Primary + +This endpoint demotes a primary cluster to a secondary. This secondary cluster +will not attempt to connect to a primary (see the update-primary call), but will +maintain knowledge of its cluster ID and can be reconnected to the same +replication set without wiping local storage. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/primary/demote` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/sys/replication/primary/demote +``` + +## Disable Primary + +This endptoin disables replication entirely on the cluster. Any secondaries will +no longer be able to connect. Caution: re-enabling this node as a primary or +secondary will change its cluster ID; in the secondary case this means a wipe of +the underlying storage when connected to a primary, and in the primary case, +secondaries connecting back to the cluster (even if they have connected before) +will require a wipe of the underlying storage. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/primary/disable` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/sys/replication/primary/disable +``` + +## Generate Secondary Token + +This endpoint generates a secondary activation token for the +cluster with the given opaque identifier, which must be unique. This +identifier can later be used to revoke a secondary's access. + +**This endpoint requires 'sudo' capability.** + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/sys/replication/primary/secondary-token` | `200 application/json` | + +### Parameters + +- `id` `(string: )` – Specifies an opaque identifier, e.g. 'us-east' + +- `ttl` `(string: "30m")` – Specifies the TTL for the secondary activation + token. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/sys/replication/primary/secondary-token?id=us-east-1 +``` + +### Sample Response + +```json +{ + "request_id": "", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": null, + "warnings": null, + "wrap_info": { + "token": "fb79b9d3-d94e-9eb6-4919-c559311133d6", + "ttl": 300, + "creation_time": "2016-09-28T14:41:00.56961496-04:00", + "wrapped_accessor": "" + } +} +``` + +## Revoke Secondary Token + +This endpoint revokes a secondary's ability to connect to the primary cluster; +the secondary will immediately be disconnected and will not be allowed to +connect again unless given a new activation token. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/secondary/revoke-secondary` | `204 (empty body)` | + +### Parameters + +- `id` `(string: )` – Specifies an opaque identifier, e.g. 'us-east' + +### Sample Payload + +```json +{ + "id": "us-east" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/replication/secondary/revoke-secondary +``` + +## Enable Secondary + +This endpoint enables replication on a secondary using a secondary activation +token. + +!> This will immediately clear all data in the secondary cluster! + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/secondary/enable` | `204 (empty body)` | + +### Parameters + +- `token` `(string: )` – Specifies the secondary activation token fetched from the primary. + +- `primary_api_addr` `(string: "")` – Specifies Set this to the API address + (normal Vault address) to override the value embedded in the token. This can + be useful if the primary's redirect address is not accessible directly from + this cluster (e.g. through a load balancer). + +- `ca_file` `(string: "")` – Specifies the path to a CA root file (PEM format) + that the secondary can use when unwrapping the token from the primary. If this + and ca_path are not given, defaults to system CA roots. + +- `ca_path` `(string: "")` – Specifies the path to a CA root directory + containing PEM-format files that the secondary can use when unwrapping the + token from the primary. If this and ca_file are not given, defaults to system + CA roots. + +### Sample Payload + +```json +{ + "token": "..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/replication/secondary/enable +``` + +## Promote Secondary + +This endpoint promotes the secondary cluster to primary. For data safety and +security reasons, new secondary tokens will need to be issued to other +secondaries, and there should never be more than one primary at a time. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/secondary/promote` | `204 (empty body)` | + +### Parameters + +- `primary_cluster_addr` `(string: "")` – Specifies the cluster address that the + primary gives to secondary nodes. Useful if the primary's cluster address is + not directly accessible and must be accessed via an alternate path/address + (e.g. through a load balancer). + +### Sample Payload + +```json +{} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/replication/secondary/promote +``` + +## Disable Secondary + +This endpoint disables replication entirely on the cluster. The cluster will no +longer be able to connect to the primary. + +!> Re-enabling this node as a primary or secondary will change its cluster ID; +in the secondary case this means a wipe of the underlying storage when connected +to a primary, and in the primary case, secondaries connecting back to the +cluster (even if they have connected before) will require a wipe of the +underlying storage. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/secondary/disable` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/sys/replication/secondary/disable +``` + +## Update Secondary's Primary + +This endpoint changes a secondary cluster's assigned primary cluster using a +secondary activation token. This does not wipe all data in the cluster. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/sys/replication/secondary/update-primary` | `204 (empty body)` | + +### Parameters + +- `token` `(string: )` – Specifies the secondary activation token + fetched from the primary. If you set this to a blank string, the cluster will + stay a secondary but clear its knowledge of any past primary (and thus not + attempt to connect to the previous primary). This can be useful if the primary + is down to stop the secondary from trying to reconnect to it. + +- `primary_api_addr` `(string: )` – Specifies the API address (normal Vault + address) to override the value embedded in the token. This can be useful if + the primary's redirect address is not accessible directly from this cluster. + +- `ca_file` `(string: "")` – Specifies the path to a CA root file (PEM format) + that the secondary can use when unwrapping the token from the primary. If this + and ca_path are not given, defaults to system CA roots. + +- `ca_path` `string: ()` – Specifies the path to a CA root directory containing + PEM-format files that the secondary can use when unwrapping the token from the + primary. If this and ca_file are not given, defaults to system CA roots. + +### Sample Payload + +```json +{ + "token": "..." +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/sys/replication/secondary/update-primary +``` diff --git a/website/source/docs/vault-enterprise/replication/index.html.md b/website/source/docs/vault-enterprise/replication/index.html.md index 6627b32c3..c37b04f06 100644 --- a/website/source/docs/vault-enterprise/replication/index.html.md +++ b/website/source/docs/vault-enterprise/replication/index.html.md @@ -33,7 +33,7 @@ Multiple Vault clusters communicate in a one-to-many near real-time flow. The primary cluster acts as the system or record and asynchronously replicates most Vault data to a series of remote clusters, known as secondary clusters or -secondaries. +secondaries. The secondaries keep track of their own tokens and leases but share the underlying configuration, policies, and supporting secrets (K/V values, @@ -137,9 +137,6 @@ around operationalizing the replication feature. ## API -API documents are available with the endpoints relevant to the -[primary](https://www.vaultproject.io/docs/http/sys-replication-primary.html) -cluster, the -[secondary](https://www.vaultproject.io/docs/http/sys-replication-secondary.html) -cluster, and endpoints [relevant to -both](https://www.vaultproject.io/docs/http/sys-replication.html). +The Consul replication component has a full HTTP API. Please see the +[Vault Replication API](/docs/http/system/replication.html) for more +details. diff --git a/website/source/layouts/http.erb b/website/source/layouts/http.erb index 281c78d1b..886845376 100644 --- a/website/source/layouts/http.erb +++ b/website/source/layouts/http.erb @@ -117,6 +117,9 @@ > /sys/renew + > + /sys/replication + > /sys/revoke From bfa7fe9a3efdab3fb75fe54064bddcc371dd4e29 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 12:04:14 -0700 Subject: [PATCH 15/17] Fix sentence --- website/source/docs/http/index.html.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/website/source/docs/http/index.html.md b/website/source/docs/http/index.html.md index 0fb620b3c..a1bf38f79 100644 --- a/website/source/docs/http/index.html.md +++ b/website/source/docs/http/index.html.md @@ -8,8 +8,6 @@ description: |- # HTTP API -The Vault HTTP API is a - The Vault HTTP API gives you full access to Vault via HTTP. Every aspect of Vault can be controlled via this API. The Vault CLI uses the HTTP API to access Vault. From 0f845ef67d950528f506478b8f846d03d3cb5fa0 Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 12:04:36 -0700 Subject: [PATCH 16/17] Use relative links --- website/source/docs/auth/app-id.html.md | 2 +- website/source/docs/auth/approle.html.md | 2 +- website/source/docs/auth/aws-ec2.html.md | 2 +- website/source/docs/concepts/dev-server.html.md | 2 +- website/source/docs/concepts/policies.html.md | 2 +- .../source/docs/concepts/response-wrapping.html.md | 6 +++--- website/source/docs/concepts/tokens.html.md | 6 +++--- .../docs/guides/upgrading/upgrade-to-0.6.0.html.md | 2 +- .../docs/guides/upgrading/upgrade-to-0.6.1.html.md | 12 ++++++------ .../docs/guides/upgrading/upgrade-to-0.6.2.html.md | 2 +- website/source/docs/secrets/cubbyhole/index.html.md | 2 +- .../docs/vault-enterprise/replication/index.html.md | 4 ++-- 12 files changed, 22 insertions(+), 22 deletions(-) diff --git a/website/source/docs/auth/app-id.html.md b/website/source/docs/auth/app-id.html.md index ae2110322..bf8b7e8ad 100644 --- a/website/source/docs/auth/app-id.html.md +++ b/website/source/docs/auth/app-id.html.md @@ -13,7 +13,7 @@ Name: `app-id` ## Deprecation Notice As of Vault 0.6.1, App ID is deprecated in favor of -[AppRole](https://www.vaultproject.io/docs/auth/approle.html). AppRole can +[AppRole](/docs/auth/approle.html). AppRole can accommodate the same workflow as App ID while enabling much more secure and flexible management and other types of authentication workflows. No new features or enhancements are planned for App ID, and new users should use diff --git a/website/source/docs/auth/approle.html.md b/website/source/docs/auth/approle.html.md index bd9d07bb7..fbfc26579 100644 --- a/website/source/docs/auth/approle.html.md +++ b/website/source/docs/auth/approle.html.md @@ -58,7 +58,7 @@ entry, even if these are then distributed via different paths. However, in Pull mode, even though the RoleID must be known in order to distribute it to the client, the SecretID can be kept confidential from all parties except for the final authenticating client by using [Response -Wrapping](https://www.vaultproject.io/docs/concepts/response-wrapping.html). +Wrapping](/docs/concepts/response-wrapping.html). Push mode is available for App-ID workflow compatibility, which in some specific cases is preferable, but in most cases Pull mode is more secure and diff --git a/website/source/docs/auth/aws-ec2.html.md b/website/source/docs/auth/aws-ec2.html.md index b9545fe67..e1703eb7b 100644 --- a/website/source/docs/auth/aws-ec2.html.md +++ b/website/source/docs/auth/aws-ec2.html.md @@ -145,7 +145,7 @@ not specify the policy component, the client will inherit the allowed policies s on the role. If the role tag creation specifies the policy component but it contains no policies, the token will contain only the `default` policy; by default, this policy allows only manipulation (revocation, renewal, lookup) of the existing token, plus -access to its [cubbyhole](https://www.vaultproject.io/docs/secrets/cubbyhole/index.html). +access to its [cubbyhole](/docs/secrets/cubbyhole/index.html). This can be useful to allow instances access to a secure "scratch space" for storing data (via the token's cubbyhole) but without granting any access to other resources provided by or resident in Vault. diff --git a/website/source/docs/concepts/dev-server.html.md b/website/source/docs/concepts/dev-server.html.md index 8d8b278a0..d3e33171f 100644 --- a/website/source/docs/concepts/dev-server.html.md +++ b/website/source/docs/concepts/dev-server.html.md @@ -46,7 +46,7 @@ The properties of the dev server: The dev server should be used for experimentation with Vault features, such as different authentication backends, secret backends, audit backends, etc. If you're new to Vault, you may want to pick up with [Your First -Secret](https://www.vaultproject.io/intro/getting-started/first-secret.html) in +Secret](/intro/getting-started/first-secret.html) in our getting started guide. In addition to experimentation, the dev server is very easy to automate diff --git a/website/source/docs/concepts/policies.html.md b/website/source/docs/concepts/policies.html.md index 0899c0212..1981c6485 100644 --- a/website/source/docs/concepts/policies.html.md +++ b/website/source/docs/concepts/policies.html.md @@ -143,7 +143,7 @@ values) that a user is allowed to specify when calling a path. These parameters can be used to set minimums/maximums on TTLs set by clients when requesting that a response be -[wrapped](https://www.vaultproject.io/docs/concepts/response-wrapping.html), with a granularity of a second. These can either be specified as a number of seconds or a string with a `s`, `m`, or `h` suffix indicating seconds, minutes, and hours respectively. +[wrapped](/docs/concepts/response-wrapping.html), with a granularity of a second. These can either be specified as a number of seconds or a string with a `s`, `m`, or `h` suffix indicating seconds, minutes, and hours respectively. In practice, setting a minimum TTL of one second effectively makes response wrapping mandatory for a particular path. diff --git a/website/source/docs/concepts/response-wrapping.html.md b/website/source/docs/concepts/response-wrapping.html.md index 9167ea7fc..be1e118d6 100644 --- a/website/source/docs/concepts/response-wrapping.html.md +++ b/website/source/docs/concepts/response-wrapping.html.md @@ -18,7 +18,7 @@ accidental disclosure, especially if the secret is being transmitted in plaintext. In Vault 0.3 the -[`cubbyhole`](https://www.vaultproject.io/docs/secrets/cubbyhole/index.html) +[`cubbyhole`](/docs/secrets/cubbyhole/index.html) backend was introduced, providing storage scoped to a single token. The [Cubbyhole Principles blog post](https://www.hashicorp.com/blog/vault-cubbyhole-principles.html) described @@ -33,11 +33,11 @@ Starting in 0.6, this concept is taken to its logical conclusion: almost every response that Vault generates can be automatically wrapped inside a single-use, limited-time-to-live token's cubbyhole. Details can be found in the [`cubbyhole` backend -documentation](https://www.vaultproject.io/docs/secrets/cubbyhole/index.html). +documentation](/docs/secrets/cubbyhole/index.html). This capability should be carefully considered when planning your security architecture. For instance, many Vault deployments use the -[`pki`](https://www.vaultproject.io/docs/secrets/pki/index.html) backend to +[`pki`](/docs/secrets/pki/index.html) backend to generate TLS certificates and private keys for services. If you do not wish these services to have access to the generation API, a trusted third party could generate the certificates and private keys and pass the resulting diff --git a/website/source/docs/concepts/tokens.html.md b/website/source/docs/concepts/tokens.html.md index 90c3f81c5..a048856c8 100644 --- a/website/source/docs/concepts/tokens.html.md +++ b/website/source/docs/concepts/tokens.html.md @@ -37,7 +37,7 @@ Read on for a deeper dive into token concepts. Often in documentation or in help channels, the "token store" is referenced. This is the same as the [`token` authentication -backend](https://www.vaultproject.io/docs/auth/token.html). This is a special +backend](/docs/auth/token.html). This is a special backend in that it is responsible for creating and storing tokens, and cannot be disabled. It is also the only authentication backend that has no login capability -- all actions require existing authenticated tokens. @@ -63,7 +63,7 @@ used for just enough initial setup (usually, setting up authentication backends and policies necessary to allow administrators to acquire more limited tokens) or in emergencies, and are revoked immediately after they are no longer needed. If a new root token is needed, the `generate-root` command and associated [API -endpoint](https://www.vaultproject.io/docs/http/sys-generate-root.html) can be +endpoint](/docs/http/sys-generate-root.html) can be used to generate one on-the-fly. It is also good security practice for there to be multiple eyes on a terminal @@ -149,7 +149,7 @@ token's information is looked up. It is based on a combination of factors: 1. The system max TTL, which is 32 days but can be changed in Vault's configuration file 2. The max TTL set on a mount using [mount - tuning](https://www.vaultproject.io/docs/http/sys-mounts.html). This value + tuning](/docs/http/sys-mounts.html). This value is allowed to override the system max TTL -- it can be longer or shorter, and if set this value will be respected. 3. A value suggested by the authentication backend that issued the token. This diff --git a/website/source/docs/guides/upgrading/upgrade-to-0.6.0.html.md b/website/source/docs/guides/upgrading/upgrade-to-0.6.0.html.md index ecda76886..dd291ca75 100644 --- a/website/source/docs/guides/upgrading/upgrade-to-0.6.0.html.md +++ b/website/source/docs/guides/upgrading/upgrade-to-0.6.0.html.md @@ -51,5 +51,5 @@ If using the Consul HA storage backend, Vault will now automatically register itself as the `vault` service and perform its own health checks/lifecycle status management. This behavior can be adjusted or turned off in Vault's configuration; see the -[documentation](https://www.vaultproject.io/docs/config/index.html#check_timeout) +[documentation](/docs/config/index.html#check_timeout) for details. diff --git a/website/source/docs/guides/upgrading/upgrade-to-0.6.1.html.md b/website/source/docs/guides/upgrading/upgrade-to-0.6.1.html.md index 332dcd57b..751400800 100644 --- a/website/source/docs/guides/upgrading/upgrade-to-0.6.1.html.md +++ b/website/source/docs/guides/upgrading/upgrade-to-0.6.1.html.md @@ -16,7 +16,7 @@ carefully. Once an active node is running 0.6.1, only standby nodes running 0.6.1+ will be able to form an HA cluster. If following our [general upgrade -instructions](https://www.vaultproject.io/docs/install/upgrade.html) this will +instructions](/docs/install/upgrade.html) this will not be an issue. ## Health Endpoint Status Code Changes @@ -39,7 +39,7 @@ each status code (including `500`). Root tokens (tokens with the `root` policy) can no longer be created except by another root token or the -[`generate-root`](https://www.vaultproject.io/docs/http/sys-generate-root.html) +[`generate-root`](/docs/http/sys-generate-root.html) endpoint or CLI command. ## PKI Backend Certificates Will Contain Default Key Usages @@ -50,14 +50,14 @@ compatibility with some software that requires strict adherence to RFCs, such as OpenVPN. This behavior is fully adjustable; see the [PKI backend -documentation](https://www.vaultproject.io/docs/secrets/pki/index.html) for +documentation](/docs/secrets/pki/index.html) for details. ## DynamoDB Does Not Support HA By Default If using DynamoDB and want to use HA support, you will need to explicitly enable it in Vault's configuration; see the -[documentation](https://www.vaultproject.io/docs/config/index.html#ha_enabled) +[documentation](/docs/config/index.html#ha_enabled) for details. If you are already using DynamoDB in an HA fashion and wish to keep doing so, @@ -83,7 +83,7 @@ unfortunately has the side effect that `memberOf` is no longer searched for by default, which is a breaking change for many existing setups. `Scenario 2` in the [updated -documentation](https://www.vaultproject.io/docs/auth/ldap.html) shows an +documentation](/docs/auth/ldap.html) shows an example of configuring the backend to query `memberOf`. It is recommended that a test Vault server be set up and that successful authentication can be performed using the new configuration before upgrading a primary or production @@ -97,7 +97,7 @@ configuration can be specified successfully. ## App-ID is Deprecated With the addition of of the new [AppRole -backend](https://www.vaultproject.io/docs/auth/approle.html), App-ID is +backend](/docs/auth/approle.html), App-ID is deprecated. There are no current plans to remove it, but we encourage using AppRole whenever possible, as it offers enhanced functionality and can accommodate many more types of authentication paradigms. App-ID will receive diff --git a/website/source/docs/guides/upgrading/upgrade-to-0.6.2.html.md b/website/source/docs/guides/upgrading/upgrade-to-0.6.2.html.md index 930fae248..1f05da155 100644 --- a/website/source/docs/guides/upgrading/upgrade-to-0.6.2.html.md +++ b/website/source/docs/guides/upgrading/upgrade-to-0.6.2.html.md @@ -16,7 +16,7 @@ for Vault 0.6.2. Please read it carefully. In 0.6.1 this feature was in beta and required opting-in, but is now enabled by default. This can be disabled via the `"disable_clustering"` parameter in -Vault's [config](https://www.vaultproject.io/docs/config/index.html), or +Vault's [config](/docs/config/index.html), or per-request with the `X-Vault-No-Request-Forwarding` header. ## AppRole Role Constraints diff --git a/website/source/docs/secrets/cubbyhole/index.html.md b/website/source/docs/secrets/cubbyhole/index.html.md index 79d91f8b6..06b7581f5 100644 --- a/website/source/docs/secrets/cubbyhole/index.html.md +++ b/website/source/docs/secrets/cubbyhole/index.html.md @@ -31,7 +31,7 @@ the sub-fields are not merged together. Starting in Vault 0.6, almost any response (except those from `sys/` endpoints) from Vault can be wrapped (see the [Response -Wrapping](https://www.vaultproject.io/docs/concepts/response-wrapping.html) +Wrapping](/docs/concepts/response-wrapping.html) concept page for details). The TTL for the token is set by the client using the `X-Vault-Wrap-TTL` header diff --git a/website/source/docs/vault-enterprise/replication/index.html.md b/website/source/docs/vault-enterprise/replication/index.html.md index c37b04f06..b375305b9 100644 --- a/website/source/docs/vault-enterprise/replication/index.html.md +++ b/website/source/docs/vault-enterprise/replication/index.html.md @@ -75,7 +75,7 @@ horizontally. Details on the internal design of the replication feature can be found in the [replication -internals](https://www.vaultproject.io/docs/internals/replication.html) +internals](/docs/internals/replication.html) document. ## Security Model @@ -131,7 +131,7 @@ its encrypted barrier. ## Setup and Best Practices -A [setup guide](https://www.vaultproject.io/docs/guides/replication.html) is +A [setup guide](/docs/guides/replication.html) is available to help you get started; this guide also contains best practices around operationalizing the replication feature. From 05e8b1861f9eaa63c4f1db378a15574c8a105c4f Mon Sep 17 00:00:00 2001 From: Seth Vargo Date: Thu, 16 Mar 2017 12:06:15 -0700 Subject: [PATCH 17/17] Formatting --- website/source/layouts/docs.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 053db3a7c..30e6f5c34 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -339,7 +339,7 @@ Replication
  • > - Secure Introduction Client + Secure Introduction